fix(workflows): ensure workflow-builder injects $ARGUMENTS in generated YAMLs

[kagura-agent]

Summary

• Problem: archon-workflow-builder generates single-node workflows whose prompt templates describe user input in prose but never include the $ARGUMENTS substitution variable. The harness captures the user's invocation message as workflow_start.content but it is never injected into the node's conversation — the agent asks the user to re-provide input they already gave.
• Why it matters: Every single-node workflow generated by the builder is broken for user-input use cases. Users must manually patch the YAML to add $ARGUMENTS.
• What changed: Added rule 13 to generate-yaml prompt requiring $ARGUMENTS in generated workflows that accept user input. Added validation warning in validate-yaml when the variable is missing.
• What did not change: No changes to the workflow engine, variable substitution logic, or any TypeScript code. Only the bundled workflow-builder prompt and its validation bash script.

Closes #1535

UX Journey

Before

User                         Archon Workflow Builder            Generated Workflow
────                         ──────────────────────            ──────────────────
"build sparc workflow" ────▶ scans codebase
                             extracts intent
                             generates YAML ─────────────────▶ prompt says "the subject
                                                                provided by the user"
                                                                but NO $ARGUMENTS token

User runs workflow:
"topic: quantum" ──────────▶ harness captures message
                             BUT node prompt has no $ARGUMENTS
                             agent sees empty input ──────────▶ "Please provide a topic"

After

User                         Archon Workflow Builder            Generated Workflow
────                         ──────────────────────            ──────────────────
"build sparc workflow" ────▶ scans codebase
                             extracts intent
                             generates YAML ─────────────────▶ prompt includes:
                                                                ## Input
                                                                $ARGUMENTS
                             validates: checks for $ARGUMENTS ─▶ VALID ✓

User runs workflow:
"topic: quantum" ──────────▶ harness captures message
                             substitutes $ARGUMENTS
                             agent sees full input ───────────▶ proceeds correctly

Architecture Diagram

Before

archon-workflow-builder.yaml
├── scan-codebase (bash)
├── extract-intent (prompt, references $ARGUMENTS ✓)
├── generate-yaml (prompt, rules 1-12)      ← no rule about $ARGUMENTS in output
├── validate-yaml (bash, checks name/nodes) ← no $ARGUMENTS check
└── save-or-report (prompt)

After

archon-workflow-builder.yaml
├── scan-codebase (bash)
├── extract-intent (prompt, references $ARGUMENTS ✓)
├── [~] generate-yaml (prompt, rules 1-13)  ← rule 13: MUST include $ARGUMENTS
├── [~] validate-yaml (bash)                ← WARNING if $ARGUMENTS missing
└── save-or-report (prompt)

Connection inventory:

From	To	Status	Notes
generate-yaml	validate-yaml	modified	Rule 13 teaches AI to include $ARGUMENTS; validation warns if missing

Label Snapshot

• Risk: risk: low
• Size: size: XS
• Scope: workflows
• Module: workflows:builder

Change Metadata

• Change type: bug
• Primary scope: workflows

Linked Issue

• Closes archon-workflow-builder generates single-node YAMLs that drop user input ($ARGUMENTS missing) #1535

Validation Evidence (required)

$ bun run check:bundled
bundled-defaults.generated.ts is up to date (36 commands, 20 workflows).

$ bun run type-check
All packages: Exited with code 0

$ bun run lint
# lint-staged passes on commit

• Evidence: type-check and bundled-defaults check pass. Lint runs via lint-staged on commit.
• bun run test skipped: change is prompt-only (YAML text), no TypeScript logic affected.

Security Impact (required)

• New permissions/capabilities? No
• New external network calls? No
• Secrets/tokens handling changed? No
• File system access scope changed? No

Compatibility / Migration

• Backward compatible? Yes — only affects newly generated workflows
• Config/env changes? No
• Database migration needed? No

Human Verification (required)

• Verified: diff review confirms only prompt text and validation script changed
• Verified: bun run generate:bundled regenerates cleanly with the new content
• Edge cases: workflows that intentionally don't take user input (e.g., pure codebase scan) — the validation emits a WARNING not an ERROR, so they still pass
• Not verified: end-to-end workflow generation (requires running the full workflow-builder with an AI model)

Side Effects / Blast Radius (required)

• Affected: only archon-workflow-builder bundled default workflow
• Potential effects: AI may now always include $ARGUMENTS even in workflows that don't need user input — but since rule 13 says "that accepts user input", the AI should discriminate correctly
• Guardrails: validation is a WARNING not ERROR, so false positives don't block

Rollback Plan (required)

• Revert this commit and run bun run generate:bundled
• No feature flags needed — prompt-only change
• Observable failure: if somehow rule 13 causes the AI to produce invalid YAML, the existing name/nodes validation will catch it

Risks and Mitigations

• Risk: AI may over-apply rule 13 and inject $ARGUMENTS into workflows that purely scan without user input
  • Mitigation: Rule text is scoped to "workflows that accept user input"; worst case is a harmless unused $ARGUMENTS reference

Summary by CodeRabbit

• Chores
  • Enhanced workflow validation to ensure user input is properly referenced in workflows. The system now warns when generated workflows may not receive user invocation text in node prompts.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a generation constraint and validation check to the archon-workflow-builder workflow to ensure that generated single-node workflows that accept user input reference the $ARGUMENTS or $USER_MESSAGE substitution variable in at least one node prompt. The constraint is enforced during generation, and the validation step warns when the token is missing.

Changes

Workflow user input validation

Layer / File(s)	Summary
Prompt generation constraint .archon/workflows/defaults/archon-workflow-builder.yaml	Adds a CRITICAL rule to the YAML generation prompt requiring any generated workflow that accepts user input to reference $ARGUMENTS or $USER_MESSAGE in at least one node prompt.
YAML validation and warning .archon/workflows/defaults/archon-workflow-builder.yaml, packages/workflows/src/defaults/bundled-defaults.generated.ts	The validate-yaml step now checks the generated workflow for $ARGUMENTS or $USER_MESSAGE via grep and prints a WARNING if neither is present, ensuring generated workflows properly inject user invocation text into node prompts.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A constraint whispers, "Remember $ARGUMENTS!
Validation checks: "Is it there?" With diligence.
Single-node DAGs now heed the message true,
User input flows where it's meant to—right through!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary change: ensuring $ARGUMENTS injection in generated workflow YAMLs to fix user input handling.
Description check	✅ Passed	The PR description fully addresses the template with summary bullets, UX journey, architecture diagrams, validation evidence, security assessment, and rollback plan.
Linked Issues check	✅ Passed	The PR satisfies issue #1535 objectives by adding rule 13 to require $ARGUMENTS in generated workflows and validation warnings for missing references.
Out of Scope Changes check	✅ Passed	All changes are scoped to the archon-workflow-builder prompt and validation logic; no unrelated code modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

.archon/workflows/defaults/archon-workflow-builder.yaml (1)

227-229: 💤 Low value

Consider enhancing the warning message with an actionable suggestion.

The validation correctly detects missing input tokens and emits a warning without blocking the workflow. The implementation is sound. The warning message could be slightly more actionable by suggesting the fix.

💡 Optional: More actionable warning message

       if ! grep -q '\$ARGUMENTS\|\$USER_MESSAGE' "$FILE"; then
-        echo "WARNING: workflow does not reference \$ARGUMENTS or \$USER_MESSAGE — user input will not be injected into node prompts"
+        echo "WARNING: workflow does not reference \$ARGUMENTS or \$USER_MESSAGE — user input will not be injected into node prompts. Consider adding '\$ARGUMENTS' to a prompt node if this workflow should accept user input."
       fi

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.archon/workflows/defaults/archon-workflow-builder.yaml around lines 227 -
229, The current warning emitted when the grep check for '$ARGUMENTS' or
'$USER_MESSAGE' on FILE fails is informative but not actionable; update the echo
message inside the conditional that checks if ! grep -q
'\$ARGUMENTS\|\$USER_MESSAGE' "$FILE" to include a concise remediation hint
(e.g., instruct users to add $ARGUMENTS or $USER_MESSAGE into the relevant node
prompt or point them to the workflow docs/example) so the message suggests how
to fix the missing tokens.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.archon/workflows/defaults/archon-workflow-builder.yaml:
- Around line 227-229: The current warning emitted when the grep check for
'$ARGUMENTS' or '$USER_MESSAGE' on FILE fails is informative but not actionable;
update the echo message inside the conditional that checks if ! grep -q
'\$ARGUMENTS\|\$USER_MESSAGE' "$FILE" to include a concise remediation hint
(e.g., instruct users to add $ARGUMENTS or $USER_MESSAGE into the relevant node
prompt or point them to the workflow docs/example) so the message suggests how
to fix the missing tokens.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 603ff632-7728-4db4-ae07-8d93b3a163f9

📥 Commits

Reviewing files that changed from the base of the PR and between 5283ea9 and 9bec9ba.

📒 Files selected for processing (2)

• .archon/workflows/defaults/archon-workflow-builder.yaml
• packages/workflows/src/defaults/bundled-defaults.generated.ts

[Wirasm]

Review Summary

Verdict: ready-to-merge

This PR adds a runtime validation step to the workflow builder that warns when a generated workflow may silently drop user input by omitting references to $ARGUMENTS or $USER_MESSAGE. The change is minimal, focused, and follows existing patterns in the codebase. No issues found.

Blocking issues

None.

Suggested fixes

None.

Minor / nice-to-have

None — the implementation is clean and the soft WARNING approach (vs. hard exit 1) is a sensible design choice that avoids blocking edge cases.

Compliments

• The validation check is implemented as a WARNING rather than a hard failure, which is the right call for a workflow builder — it alerts without blocking legitimate uses.
• No breaking changes introduced; all changes stay within YAML workflow conventions.

---

Reviewed via maintainer-review-pr workflow (Pi/Minimax). Aspects run: code-review.