Add guardrails, decision rationale, and migration path for campaign workflow creation

docs/src/content/docs/guides/campaigns/getting-started.md

@@ -10,6 +10,17 @@ This guide is the shortest path from “we want a campaign” to a working dashb
 > Using [agentic workflows](/gh-aw/reference/glossary/#agentic-workflow) (AI-powered workflows that can make autonomous decisions) means giving AI [agents](/gh-aw/reference/glossary/#agent) (autonomous AI systems) the ability to make decisions and take actions in your repository. This requires careful attention to security considerations and human supervision.
 > Review all outputs carefully and use time-limited trials to evaluate effectiveness for your team.
 
+## Campaign Best Practices
+
+Before creating your first campaign, keep these core principles in mind:
+
+- **Start small**: One clear goal per campaign (e.g., "Upgrade Node.js to v20")
+- **Start passive**: Use passive mode first to observe behavior and build trust
+- **Reuse workflows**: Search existing workflows before creating new ones
+- **Minimal permissions**: Grant only necessary permissions (issues/draft PRs, not merges)
+- **Standardized outputs**: Use consistent patterns for issues, PRs, and comments
+- **Escalate when uncertain**: Create issues requesting human review for risky decisions
+
 ## Quick start (5 steps)
 
 1. Create a GitHub Project board (manual, one-time) and copy its URL.
@@ -35,6 +46,38 @@ Copy the Project URL (e.g., `https://github.com/orgs/myorg/projects/42`).
 
 Create `.github/workflows/<id>.campaign.md` with frontmatter like:
 
+**For your first campaign** (passive mode - recommended):
+
+```yaml
+id: framework-upgrade
+version: "v1"
+name: "Framework Upgrade"
+
+project-url: "https://github.com/orgs/ORG/projects/1"
+tracker-label: "campaign:framework-upgrade"
+
+objective: "Upgrade all services to Framework vNext with zero downtime."
+kpis:
+  - id: services_upgraded
+    name: "Services upgraded"
+    priority: primary
+    direction: "increase"
+    baseline: 0
+    target: 50
+    time-window-days: 30
+
+workflows:
+  - framework-upgrade  # Use an existing workflow
+
+# Governance (conservative defaults for first campaign)
+governance:
+  max-new-items-per-run: 5
+  max-project-updates-per-run: 5
+  max-comments-per-run: 3
+```
+
+**For experienced users** (active mode - advanced):
+
 ```yaml
 id: framework-upgrade
 version: "v1"
@@ -47,15 +90,31 @@ objective: "Upgrade all services to Framework vNext with zero downtime."
 kpis:
   - id: services_upgraded
     name: "Services upgraded"
-    primary: true
+    priority: primary
     direction: "increase"
+    baseline: 0
     target: 50
+    time-window-days: 30
 
 workflows:
-  - framework-upgrade
+  - framework-scanner
+  - framework-upgrader
+
+# Enable active execution (ADVANCED - only after passive campaign experience)
+execute-workflows: true
+
+# Governance (still start conservative even in active mode)
+governance:
+  max-new-items-per-run: 10
+  max-project-updates-per-run: 10
+  max-comments-per-run: 5
 ```
 
-You can add governance and repo-memory wiring later; start with a working loop.
+**Key differences:**
+- **Passive mode**: Discovers and tracks work created by existing workflows (safer, simpler)
+- **Active mode**: Can execute workflows and create missing ones (powerful but complex)
+
+**Start passive** unless you have prior campaign experience. You can enable active execution later.
 
 ## 3) Compile
 
@@ -96,6 +155,50 @@ Items with campaign labels (`campaign:*`) are automatically protected from other
 
 This ensures your campaign items remain under the control of the campaign orchestrator and aren't interfered with by other workflows.
 
+## Migrating from Passive to Active Mode
+
+Once you've successfully run a passive campaign for 1-2 weeks and understand how it works, you can enable active execution:
+
+**Prerequisites before enabling active mode:**
+1. ✅ You've run at least 2-3 passive campaign runs successfully
+2. ✅ You understand how the orchestrator coordinates work
+3. ✅ You've reviewed the project board and it's tracking items correctly
+4. ✅ You have clear governance rules and conservative limits set
+
+**Migration steps:**
+
+1. **Update your campaign spec** to add `execute-workflows: true`:
+   ```yaml
+   execute-workflows: true  # Enable active execution
+
+   governance:
+     max-new-items-per-run: 10  # Start conservative
+     max-project-updates-per-run: 10
+     max-comments-per-run: 5
+   ```
+
+2. **Recompile** the campaign: `gh aw compile <campaign-id>`
+
+3. **Test with a manual run** before scheduling:
+   - Trigger the workflow manually from GitHub Actions
+   - Watch the run logs carefully
+   - Verify it behaves as expected
+
+4. **Monitor closely** for the first few runs:
+   - Check that workflows execute correctly
+   - Review any new workflows it creates
+   - Ensure governance limits are appropriate
+
+5. **Adjust governance** based on observed behavior:
+   - Increase limits if runs are too conservative
+   - Decrease limits if runs are too aggressive
+   - Add opt-out labels if needed
+
+**Rollback if needed:**
+- Remove `execute-workflows: true` from spec
+- Recompile: `gh aw compile <campaign-id>`
+- Campaign reverts to passive mode
+
 ## Optional: repo-memory for durable state
 
 Enable repo-memory for campaigns using this layout: `memory/campaigns/<campaign-id>/cursor.json` and `memory/campaigns/<campaign-id>/metrics/<date>.json`. Campaign writes must include a cursor and at least one metrics snapshot.