From 122eca8e1b9c7898e4f644ef08beb7e85f1cd226 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Tue, 20 Oct 2026 13:17:00 +0100 Subject: [PATCH] docs: require an explicit request before authoring pipelines Use existing pipelines for run requests and put task specifics in the run prompt. Creation, edits and publication now require an explicit user request; the authoring skill test enforces that guidance. --- AGENTS.md | 12 ++++++++++++ internal/author/manager/SKILL.md | 4 ++++ internal/author/skill/SKILL.md | 13 +++++++++++++ internal/author/skill_reference_test.go | 2 +- 4 files changed, 30 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 51b5145f..4d27eca6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,18 @@ The manager may implement, review, fix tests, resolve conflicts, merge and deliv When a pipeline blocks progress, diagnose it and take over directly when useful. Do not create another recovery workflow just to complete an existing item. +## Pipelines are selected, not invented + +- For a task that can run in a pipeline, select an existing pipeline and put the + task-specific detail in the run prompt. Do not create a pipeline or a new + version because an existing prompt does not fit exactly. +- Create, edit, or publish a pipeline only when the user explicitly asks for that + pipeline change in the current conversation. This includes `pipelines new`, + `pipelines edit`, `pipelines submit`, draft/import flows, and publishing through + `rpc`, the API, or direct database writes. +- Never publish a pipeline version as a side effect of solving a run request. If + no existing pipeline fits, stop and report the gap; ask before authoring. + ## Small changes, parallel progress Split features into small independently testable changes. Keep stage roles and diff --git a/internal/author/manager/SKILL.md b/internal/author/manager/SKILL.md index fd67d714..f7120f87 100644 --- a/internal/author/manager/SKILL.md +++ b/internal/author/manager/SKILL.md @@ -10,6 +10,10 @@ a dispatcher that can only launch pipelines. You may inspect, implement, test, review, resolve conflicts, merge and deliver directly. Pipelines are tools, not an exclusive route or a reason to leave finished work stranded. +Use an existing pipeline for pipeline-shaped work. Do not create, edit, or +publish a pipeline or version unless the user explicitly asked for that change; +put task specifics in the run prompt instead. If none fits, report the gap. + Split work into small independently testable items. Keep prompts and handoffs short and specialized. Run independent items in parallel, accepting manageable merge conflicts. Use the agreed model; do not silently escalate cost. diff --git a/internal/author/skill/SKILL.md b/internal/author/skill/SKILL.md index 640e4c64..08af722b 100644 --- a/internal/author/skill/SKILL.md +++ b/internal/author/skill/SKILL.md @@ -19,6 +19,19 @@ A failed run keeps its worktree and commits. Read `pipelines inspect --json before deciding: resume the failed stage (`pipelines retry `), fix directly, or continue from the preserved branch. +## Use an existing pipeline + +A request to run work is not a request to author. `pipelines list` and +`pipelines search` come before `pipelines new`. Use the closest existing +workflow and put task-specific requirements in the run prompt; a pipeline prompt +is deliberately generic and does not need to match every request word for word. + +Never create, edit, submit, import, or publish a pipeline or version merely to +complete a run request. Those actions require an explicit request from the user +in the current conversation. If no existing pipeline can do the work, stop and +explain the gap; ask before authoring. Do not add a task-specific pipeline as a +"safer" alternative to direct work or an existing workflow. + ## Authoring A definition is Markdown: `# stage ` sections with `prompt`, `configs`, diff --git a/internal/author/skill_reference_test.go b/internal/author/skill_reference_test.go index 2cb34562..97fc6249 100644 --- a/internal/author/skill_reference_test.go +++ b/internal/author/skill_reference_test.go @@ -43,7 +43,7 @@ func TestEveryEmbeddedReferenceIsInstalledAndLinksResolve(t *testing.T) { if len(main) > 8000 { t.Fatal("keep detailed knowledge out of the main skill", len(main)) } - for _, required := range []string{"operations.md", "transfer.md", "verification.md", "access.md", "Only `# outcome`", "Ask about real ambiguity"} { + for _, required := range []string{"operations.md", "transfer.md", "verification.md", "access.md", "Only `# outcome`", "Ask about real ambiguity", "A request to run work is not a request to author", "Never create, edit, submit, import, or publish"} { if !strings.Contains(string(main), required) { t.Fatal("missing routing or safety rule", required) }