fix: prefer enqueue over preflight DAG checks

yottahmd · yottahmd · commit 2d8f5fcef38a · 2026-03-18T23:08:21.000+09:00
diff --git a/internal/agent/system_prompt.txt b/internal/agent/system_prompt.txt
@@ -141,7 +141,7 @@ env:
   - B: ${A}/bar
 ```
 
-Parameter values with spaces must be quoted: `dagu start dag -- name="John Doe"`. Unquoted `name=John Doe` splits into two separate parameters.
+Parameter values with spaces must be quoted: `dagu enqueue dag -- name="John Doe"`. Unquoted `name=John Doe` splits into two separate parameters.
 </correctness>
 
 <output_documents>
@@ -214,10 +214,11 @@ This keeps the main conversation context lean and avoids token waste.
 
 ### Executing a DAG
 1. Only run when user explicitly requests execution.
-2. Start: `dagu start <dag-name>` (capture the run-id)
-3. Verify: `dagu status <dag-name> --run-id=<run-id>`
-4. On failure: `read` the log file, identify root cause, propose fix.
-5. Navigate to run: `/dag-runs/<dag-name>/<run-id>`
+2. Default to queue-based execution: `dagu enqueue <dag-name>` (capture the run-id). Use `dagu start` only if the user explicitly asks for immediate local execution instead of queueing.
+3. Do not check running jobs, queued jobs, or call `dagu status` / `dagu history` before enqueueing unless the user explicitly asks for that check or requests singleton behavior.
+4. Verify the enqueued run with `dagu status <dag-name> --run-id=<run-id>` or `dagu history <dag-name> --run-id=<run-id>`
+5. On failure: `read` the log file, identify root cause, propose fix.
+6. Navigate to run: `/dag-runs/<dag-name>/<run-id>`
 
 ### Debugging a Failed Run
 1. Status: `dagu status <dag-name> --run-id=<run-id>`
diff --git a/internal/agent/system_prompt_test.go b/internal/agent/system_prompt_test.go
@@ -228,6 +228,18 @@ func TestGenerateSystemPrompt(t *testing.T) {
 		// Fallback prompt must NOT be used.
 		assert.NotContains(t, result, "You are Dagu Assistant, an AI assistant")
 	})
+
+	t.Run("execution guidance prefers enqueue without preflight checks", func(t *testing.T) {
+		t.Parallel()
+		env := EnvironmentInfo{DAGsDir: "/dags"}
+
+		result := GenerateSystemPrompt(SystemPromptParams{Env: env, Role: auth.RoleDeveloper})
+
+		assert.Contains(t, result, "Default to queue-based execution: `dagu enqueue <dag-name>`")
+		assert.Contains(t, result, "Do not check running jobs, queued jobs")
+		assert.Contains(t, result, "dagu enqueue dag -- name=\"John Doe\"")
+		assert.NotContains(t, result, "2. Start: `dagu start <dag-name>`")
+	})
 }
 
 func TestFallbackPrompt(t *testing.T) {
diff --git a/internal/persis/fileagentskill/examples/dagu/SKILL.md b/internal/persis/fileagentskill/examples/dagu/SKILL.md
@@ -133,7 +133,7 @@ steps:
     command: deploy --env ${env} --region ${region}
 ```
 
-Override at runtime: `dagu start my-dag -- env=staging region=eu-west-1`
+Override at runtime: `dagu enqueue my-dag -- env=staging region=eu-west-1`
 
 ## Environment Variables
 
@@ -240,7 +240,9 @@ dagu schema config auth            # Auth config
 
 ## Checking Run Status
 
-After running a DAG with `dagu start`, use `dagu status` to inspect the result. The output is a tree showing each step's status, command, stdout/stderr content, and errors.
+For agent-triggered execution, prefer `dagu enqueue` over `dagu start`. Do not check whether the DAG is already running or queued before enqueueing unless the user explicitly asks for that check or requests singleton behavior.
+
+After enqueueing or starting a DAG, use `dagu status` to inspect the result. The output is a tree showing each step's status, command, stdout/stderr content, and errors.
 
 ```bash
 dagu status my-dag                          # Latest run
diff --git a/internal/persis/fileagentskill/examples_test.go b/internal/persis/fileagentskill/examples_test.go
@@ -87,3 +87,15 @@ func TestSeedExampleSkills_ValidContent(t *testing.T) {
 		assert.NotEmpty(t, skill.Knowledge, "skill %s should have knowledge", skill.ID)
 	}
 }
+
+func TestBundledDaguSkillPrefersEnqueue(t *testing.T) {
+	t.Parallel()
+
+	data, err := SkillFS().ReadFile("examples/dagu/SKILL.md")
+	require.NoError(t, err)
+
+	content := string(data)
+	assert.Contains(t, content, "Override at runtime: `dagu enqueue my-dag -- env=staging region=eu-west-1`")
+	assert.Contains(t, content, "prefer `dagu enqueue` over `dagu start`")
+	assert.Contains(t, content, "Do not check whether the DAG is already running or queued before enqueueing")
+}
