Skip to content

Conversation

Copy link
Contributor

Copilot AI commented Jan 11, 2026

Campaign creators need clearer constraints on workflow creation, explicit decision reasoning, a defined passive→active progression, and better failure/onboarding defaults.

Workflow Creation Guardrails

campaign_creation_instructions.md:

  • 5-point safety checklist (purpose, trigger, scope, testability, reusability)
  • Explicit WHEN/NEVER criteria for creating vs reusing workflows
  • Naming conventions (action-oriented, specific vs vague)

workflow_execution.md:

  • Pre-creation questions (Does it exist? Can existing be used? Is requirement clear?)
  • Mandatory test-before-use for new workflows
  • Design requirements (single purpose, minimal tools, conservative limits)

Passive → Active Migration Path

getting-started.md:

# First campaign (recommended)
workflows:
  - existing-workflow
# execute-workflows: false  # default

# After 1-2 weeks experience
execute-workflows: true
governance:
  max-new-items-per-run: 10  # start conservative

Prerequisites checklist: 2-3 successful passive runs, understand orchestration, have governance rules set.

Decision Rationale

orchestrator_instructions.md - Added "Why?" for core principles:

  • "Workers are immutable → Allows reuse across campaigns without coupling"
  • "Reads and writes are separate → Prevents race conditions"
  • "Idempotent operation → Can re-run safely if interrupted"

Phase 2 planning decisions:

  • Why explicit GitHub state: "GitHub is source of truth, inferring from labels would be unreliable"
  • Why today's date for open items: "Projects requires end_date for roadmap views"
  • Why deterministic order: "Prevents starvation, ensures fair treatment"

campaign_creation_instructions.md - Decision templates:

Good: "Use security-scanner because: scans all Go files (matches scope), creates issues (supports reporting), already tested (reduces risk)"

Poor: "Use security-scanner workflow"

Failure Handling & Onboarding

First-time user defaults:

governance:
  max-new-items-per-run: 5        # monitor impact
  max-project-updates-per-run: 5
  max-comments-per-run: 3         # avoid noise

Compilation failure behavior: Report error with context → Suggest specific fixes → Provide doc link → Keep partial files for debugging

Runtime failure behavior: Continue other work items → Report in status update → Suggest recovery actions → Maintain cursor for next run

Onboarding template in campaign body:

## First Campaign? Read This!
1. **First run** - Orchestrator initializes board, adds Epic issue
2. **Monitor** - Check board after first run
3. **Adjust** - Tune governance based on results
4. **Learn** - Status updates explain what/why

Core Campaign Principles

Added six fundamental principles that guide all campaign creation decisions:

  1. Start with one small, clear goal per campaign - Focus on single, well-defined objectives (e.g., "Upgrade Node.js to v20" not "Upgrade Node.js and refactor auth")

  2. Use passive mode first to observe and build trust - Always start passive, monitor 1-2 weeks to understand orchestration behavior before enabling active execution

  3. Reuse existing workflows before creating new ones - Thoroughly search .github/workflows/*.md and the agentics collection before creating new workflows

  4. Keep permissions minimal (issues / draft PRs, no merges) - Grant only necessary permissions, prefer read over write, use draft PRs instead of direct merges

  5. Make outputs standardized and predictable - Use consistent safe-output configurations and follow established patterns for issue/PR formatting

  6. Escalate to humans when unsure - Don't make risky decisions autonomously, create issues requesting human review with context and reasoning

These principles are documented in:

  • campaign_creation_instructions.md - Detailed "Core Campaign Principles" section with examples and rationale
  • workflow_execution.md - "Permissions and safety" guidelines
  • getting-started.md - "Campaign Best Practices" section prominently placed for new users

All changes are prompt/documentation improvements to guide agent behavior.

Original prompt

Agentic campaigns need clearer guardrails for workflow creation, a simple path from passive to active, better explanations of why decisions are made, and stronger defaults for failure and onboarding.


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

- Add workflow creation guardrails in campaign_creation_instructions.md
  - Clear criteria for when to create new workflows
  - Safety checklist before workflow creation
  - Workflow naming guidelines

- Add passive vs active campaign guidance
  - Start with passive mode (recommended for beginners)
  - Prerequisites before enabling execute-workflows
  - Migration path from passive to active

- Add decision rationale requirements
  - Examples of good vs poor decision explanations
  - Rationale for workflow selection, governance settings, KPI selection

- Improve failure handling and recovery
  - Default failure behaviors for compilation and runtime
  - First-time user support with conservative defaults
  - Onboarding guidance in campaign body

- Enhance orchestrator instructions with decision rationale
  - Explain WHY decisions are made (state management, date calculations, etc.)
  - Core principles section with explanations

- Improve workflow execution guardrails
  - Comprehensive checklist before creating workflows
  - Mandatory testing requirements for new workflows
  - Detailed guidelines with rationale for each step

- Update getting-started guide
  - Add "First Campaign? Start Here!" section
  - Show both passive and active mode examples
  - Add migration guide from passive to active mode

These changes address the problem statement by providing:
1. Clearer guardrails for workflow creation (checklists, criteria)
2. Simple path from passive to active (step-by-step migration guide)
3. Better explanations of decisions (rationale throughout)
4. Stronger defaults for failure and onboarding (conservative settings, guidance)

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
Copilot AI changed the title [WIP] Enhance guardrails and onboarding for agentic campaigns Add guardrails, decision rationale, and migration path for campaign workflow creation Jan 11, 2026
Copilot AI requested a review from mnkiefer January 11, 2026 04:07
@mnkiefer
Copy link
Contributor

@copilot

  • Start with one small, clear goal per campaign
  • Use passive mode first to observe and build trust
  • Reuse existing workflows before creating new ones
  • Keep permissions minimal (issues / draft PRs, no merges)
  • Make outputs standardized and predictable
  • Escalate to humans when unsure

- Add "Core Campaign Principles" section with 6 fundamental guidelines:
  1. Start with one small, clear goal per campaign
  2. Use passive mode first to observe and build trust
  3. Reuse existing workflows before creating new ones
  4. Keep permissions minimal (issues/draft PRs, no merges)
  5. Make outputs standardized and predictable
  6. Escalate to humans when unsure

- Update campaign_creation_instructions.md with detailed principles
- Update workflow_execution.md with permissions and safety guidelines
- Update getting-started.md with best practices section for new users

Based on feedback from @mnkiefer in PR review.

Co-authored-by: mnkiefer <8320933+mnkiefer@users.noreply.github.com>
Copy link
Contributor Author

Copilot AI commented Jan 11, 2026

@copilot

  • Start with one small, clear goal per campaign
  • Use passive mode first to observe and build trust...

Added these core principles to the documentation in commit c323853:

In campaign_creation_instructions.md - New "Core Campaign Principles" section with detailed explanations for each principle

In workflow_execution.md - Added "Permissions and safety" guidelines emphasizing minimal permissions and human escalation

In getting-started.md - Added "Campaign Best Practices" section at the top so new users see these principles immediately

All six principles are now documented with rationale and examples throughout the campaign creation flow.

@mnkiefer mnkiefer marked this pull request as ready for review January 11, 2026 04:36
@mnkiefer mnkiefer merged commit 0938348 into main Jan 11, 2026
2 checks passed
@mnkiefer mnkiefer deleted the copilot/improve-workflow-creation branch January 11, 2026 04:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants