Cognition-Partner-Workshops · devin-ai-integration · May 22, 2026
diff --git a/README.md b/README.md
@@ -1,6 +1,14 @@
 # Workshop Operator Guide
 
-Automate the provisioning and teardown of Devin Enterprise workshops using the Devin v3 API. This repo contains scripts and documentation for workshop hosts who need to stand up isolated participant environments backed by a mirror GitHub org.
+Everything a **workshop facilitator or host** needs to plan, provision, run, and tear down a Devin Enterprise workshop. This repo contains:
+
+- **Provisioning scripts** — create mirror orgs, workshop orgs, participant invites, and environment configs via the Devin v3 API
+- **Facilitator guides** — day-of logistics, pacing tips, common issues, format variations
+- **Workshop design docs** — how to create modules, workshops, and events; quality checklist; repo naming conventions
+- **General themes** — positioning narratives, architecture strengths, platform capabilities, value framing
+- **Module facilitator notes** — per-module setup, MCP configuration, and presales positioning
+
+> **Looking for the hands-on lab content?** Attendee-facing modules, workshops, and prompts live in the [workshop-metadata](https://github.com/Cognition-Partner-Workshops/workshop-metadata) repo. This repo is for the people running the event, not the people attending it.
 
 ## Architecture Overview
 
@@ -82,8 +90,26 @@ operator/
 │       └── invoke-setup.sh           # Create Devin sessions to configure env YAML
 ├── .github/workflows/
 │   └── pr-pii-check.yml             # CI workflow to block PRs with PII
+├── templates/
+│   └── event-readme.md               # Template for new event READMEs
 └── docs/
-    └── api-reference-cheatsheet.md    # Quick reference for all v3 API endpoints used
+    ├── api-reference-cheatsheet.md    # Quick reference for all v3 API endpoints used
+    ├── facilitator-guide.md           # Day-of logistics, pacing, common issues
+    ├── workshop-design-guide.md       # How to create modules, workshops, events
+    ├── quality-checklist.md           # Quality standards for workshop content
+    ├── repo-naming-convention.md      # Repo naming rules for the GH org
+    ├── runtime-resources.md           # Provisioning hosted apps for events
+    ├── general-themes/                # Positioning narratives for facilitators
+    │   ├── README.md
+    │   ├── when-to-use-devin.md
+    │   ├── architecture-strengths.md
+    │   ├── design-patterns-for-devin.md
+    │   ├── platform-capabilities.md
+    │   ├── collaboration-model.md
+    │   └── value-narratives.md
+    └── module-facilitator-notes/      # Per-module facilitator companions
+        ├── data-engineering/          # 9 facilitator notes
+        └── security/                  # 2 facilitator notes
 ```
 
 ## Workflow
@@ -254,6 +280,19 @@ This:
 1. **Clears all git permissions** from the org
 2. **Optionally deletes the org** (with `--delete-org` flag and a 5-second confirmation delay)
 
+## Facilitator Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Facilitator Guide](docs/facilitator-guide.md) | Pre-event checklist, day-of logistics, pacing, common issues, format variations |
+| [Workshop Design Guide](docs/workshop-design-guide.md) | How to create modules, workshops, and events; audience recommendations; time budgets |
+| [Quality Checklist](docs/quality-checklist.md) | Quality standards for authoring or reviewing workshop content |
+| [Repo Naming Convention](docs/repo-naming-convention.md) | Naming rules for repos in the Cognition-Partner-Workshops org |
+| [Runtime Resources](docs/runtime-resources.md) | Provisioning hosted applications for workshop events |
+| [General Themes](docs/general-themes/) | Positioning narratives: when to use Devin, architecture strengths, value framing |
+| [Module Facilitator Notes](docs/module-facilitator-notes/) | Per-module setup, MCP configuration, and presales positioning |
+| [Event README Template](templates/event-readme.md) | Starting template for new event READMEs in workshop-metadata |
+
 ## API Reference Cheatsheet
 
 See [docs/api-reference-cheatsheet.md](docs/api-reference-cheatsheet.md) for a complete reference of all Devin v3 API endpoints used by these scripts.

diff --git a/docs/facilitator-guide.md b/docs/facilitator-guide.md
@@ -0,0 +1,120 @@
+# Facilitator Guide
+
+Guide for setting up and running a Hands-on Devin Workshop.
+
+## Pre-Event Checklist (1 week before)
+
+### Repos and Code
+- [ ] Verify all required repos exist in `Cognition-Partner-Workshops` org
+- [ ] Verify repos are set up on Devin's machine (check Devin admin panel)
+- [ ] Clone repos locally to verify they're not broken
+- [ ] Check for any new CVEs in repos used for security challenges (update descriptions if needed)
+- [ ] Create any event-specific branches or GitHub Issues
+
+### Runtime Resources
+- [ ] Provision hosted application instances (if needed)
+- [ ] Verify hosted apps are accessible and healthy
+- [ ] Test credentials for hosted apps
+- [ ] Document URLs and credentials in event README
+
+### Participant Access
+- [ ] Verify all participants have Devin account access
+- [ ] Verify participants can access the GitHub org (if they need to view repos directly)
+- [ ] Prepare event site with challenge instructions
+- [ ] Send pre-event communication with setup instructions
+
+### Facilitator Preparation
+- [ ] Run through each selected challenge yourself (or with Devin) to identify gotchas
+- [ ] Prepare "hint cards" for common stuck points
+- [ ] Have backup challenges ready if primary ones are completed quickly
+- [ ] Test screen sharing and demo setup
+
+## Day-of Checklist
+
+### Setup (30 min before start)
+- [ ] Verify hosted apps are running (health check endpoints)
+- [ ] Open all relevant repos in browser tabs
+- [ ] Prepare a demo Devin session (pre-loaded, ready to show)
+- [ ] Test WiFi/network connectivity
+- [ ] Set up screen for live Devin demo
+
+### Opening (15 min)
+1. Welcome and introductions
+2. Brief Devin overview (what it is, what it can do)
+3. Show the event site with challenge instructions
+4. Explain the repo naming convention and where to find code
+5. Point out the Devin Features checklist (Appendix)
+6. Set expectations: "These are creative challenges, not exams"
+
+### During the Workshop
+- **Float and assist:** Walk around, check in on participants
+- **Watch for:** Participants stuck on authentication, repo access, or environment issues
+- **Encourage:** Trying different approaches, experimenting with Devin features
+- **Remind:** Check the Devin Features checklist — try to discover features organically
+- **Demo:** If many people are stuck on the same thing, do a quick live demo
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|---------|
+| "Devin can't find the repo" | Verify repo is set up in Devin admin. Check repo name matches exactly. |
+| "Devin is taking too long" | Normal for complex tasks. Show participants Session Insights to understand what Devin is doing. |
+| "Devin made an error" | Use this as a teaching moment — show how to provide feedback to steer Devin. |
+| "I don't know which challenge to pick" | Suggest starting with A1 (Linting) or D4 (UI Bug) — quick wins that build confidence. |
+| "Can I use a different repo?" | Yes! The challenges list "recommended" repos but "Any" means any. Encourage experimentation. |
+| "Devin's PR has conflicts" | Show how to ask Devin to resolve merge conflicts or rebase. |
+| "The hosted app is down" | Fall back to local run instructions in runtime-resources.md. |
+
+### Closing (15 min)
+1. Ask participants to share their most interesting Devin session
+2. Review the Devin Features checklist — who completed the most?
+3. Collect feedback (survey link or verbal)
+4. Share next steps: how to use Devin in their daily work
+5. Remind them to revoke any PATs created during the workshop
+
+## Post-Event
+
+- [ ] Collect and review participant feedback
+- [ ] Document any issues discovered during the workshop
+- [ ] Update challenge modules if problems were found
+- [ ] Archive event-specific resources
+- [ ] Send follow-up email with:
+  - Links to Devin documentation
+  - Links to their PRs/sessions from the workshop
+  - Contact info for questions
+
+## Workshop Format Variations
+
+### Lightning Demo (1 hour)
+- Facilitator-driven
+- Show 2-3 challenges live
+- Participants watch, then try one challenge in the remaining time
+- Best for: executive audiences, first introductions
+
+### Hands-on Half Day (4 hours)
+- 15 min intro → 4-5 challenges → 15 min closing
+- Mix categories: start easy (A1), build up (B1, C2), finish with participant choice
+- Best for: technical teams, first workshops
+
+### Full Day Deep Dive (8 hours)
+- Morning: structured labs (guided)
+- Afternoon: open exploration (participant choice)
+- Include breaks, lunch, and discussion sessions
+- Best for: dedicated enablement, teams adopting Devin
+
+### Multi-Session Series
+- Weekly 2-hour sessions over 4 weeks
+- Each session covers one category
+- Participants build on previous sessions
+- Best for: ongoing enablement programs
+
+## Proposing New Repos
+
+If participants want to bring their own representative codebase:
+
+1. Email brian.smitches@cognition.ai with:
+   - Repo URL (or description if private)
+   - What use case it would serve
+   - License information
+2. New repos will be evaluated against the [repo quality criteria](../catalog/repos.md)
+3. Approved repos will be imported following the [naming convention](repo-naming-convention.md)
diff --git a/docs/general-themes/README.md b/docs/general-themes/README.md
@@ -0,0 +1,14 @@
+# General Themes
+
+Core narratives and guidance for positioning Devin in workshops, customer engagements, and enablement materials. These documents describe **when**, **why**, and **how** to use Devin effectively — independent of any specific technology stack or industry.
+
+Reference these themes in workshop introductions, solution briefs, and talk tracks to set consistent expectations.
+
+| Document | Summary |
+|----------|---------|
+| [When to Use Devin](when-to-use-devin.md) | Trigger types (event-driven, large-scale, capacity-constrained) and the sweet spot for AI-assisted engineering |
+| [Architecture Strengths](architecture-strengths.md) | Clean-room execution with shared context layer, context retrieval, shell access, and verification model |
+| [Design Patterns](design-patterns-for-devin.md) | Proven patterns for structuring work so Devin succeeds: locally testable code, toolchain-agnostic stubs, divide-and-conquer |
+| [Platform Capabilities](platform-capabilities.md) | Scheduled sessions, playbooks, child agents, team-based operation, and Devin Review |
+| [Collaboration Model](collaboration-model.md) | The PR feedback loop, multi-user interaction, CI monitoring, and hibernation/resume behavior |
+| [Value Narratives](value-narratives.md) | How to frame Devin's impact: capacity unlocking, velocity, quality, risk reduction, and cost optimization |
diff --git a/docs/general-themes/architecture-strengths.md b/docs/general-themes/architecture-strengths.md
@@ -0,0 +1,63 @@
+# Devin's Architecture Strengths
+
+## Clean-Room Execution
+
+Each Devin session runs on its own isolated VM — a controlled environment where workers are separated from each other and from systems they have not been granted access to. This isolation model preserves your existing security posture while adding autonomous engineering capacity.
+
+- **Security by default** — Devin operates within your existing access control and governance mechanisms. No lateral movement risk between sessions or systems — each worker is scoped to exactly the resources you provision
+- **Service account friendly** — Organizations provision scoped credentials (API keys, PATs, cloud IAM roles) that Devin uses to access exactly the systems it needs. This mirrors how you would onboard any new team member — with least-privilege access
+- **Ephemeral testing environments** — Devin can deploy into throwaway environments (containers, cloud sandboxes) for integration testing, then tear them down. No persistent state leaks between sessions
+- **Reproducible from scratch** — Every session starts from the same base. No "works on my machine" drift. Environment configuration is codified and versioned
+
+### Shared Context Layer
+
+While each session's runtime is isolated, Devin does not start from scratch. A shared context and configuration layer persists across every session in an organization:
+
+- **Environment configurations (VM blueprints)** — Pre-built machine images with dependencies, language runtimes, tools, and startup scripts baked in. Sessions boot ready to build, not waiting for `npm install`
+- **Knowledge notes** — Persistent, human-curated context (coding standards, architecture decisions, team conventions, domain glossary) that Devin retrieves automatically based on the task at hand
+- **Playbooks** — Repeatable procedures that encode institutional methodology. Every session that invokes a playbook follows the same proven steps — this is what enables you to scale how many workers you kick off, because each one executes the same validated process
+- **MCP servers** — Pre-configured integrations (Jira, Datadog, Confluence, Azure DevOps) available to every session in the org without per-session setup
+- **Secrets** — Scoped credentials tied to a service account identity, not individual user permissions. This separates who the agent is and what it can access from any specific user's identity — credentials flow through the platform's secrets management layer, never embedded in prompts or code
+- **Git connections** — Repository access configured at the org level. All sessions can clone and push to connected repos immediately
+
+This design gives you both: **clean-room isolation for security** and a **shared context layer for productivity**. Each worker VM is sandboxed, but the organization's accumulated knowledge and configuration flow into every session automatically.
+
+## Context Retrieval
+
+Devin retrieves context programmatically before acting — it pulls from indexed codebases, configured integrations, and remote resources rather than relying on assumptions:
+
+| Source | How Devin Uses It |
+|--------|-------------------|
+| **Git repositories** | Clones repos, reads code, understands project structure, examines history |
+| **DeepWiki** | Auto-generated architectural documentation for any indexed repo — Devin reads this to understand systems it has never seen before |
+| **MCP servers** | Model Context Protocol lets Devin call external tools as if they were local: query Jira tickets, read Datadog logs, search Confluence, browse Azure DevOps boards |
+| **Shell access** | Devin has a full Linux shell. It can `curl` APIs, query databases, run CLI tools, install packages, and execute arbitrary commands |
+| **Browser** | Devin can navigate web pages, interact with UIs, and extract information from web-based tools |
+| **Knowledge notes** | Persistent, human-curated context (coding standards, architecture decisions, team conventions) that Devin retrieves automatically based on the task at hand |
+
+## Shell and Tool Access
+
+Devin's VM is a real Linux machine. This means:
+
+- **Build locally** — `npm install && npm test`, `mvn clean verify`, `dotnet build`, `cargo test` — Devin runs your project's build and test suite exactly as a developer would
+- **Run infrastructure tools** — `terraform plan`, `aws cloudformation deploy`, `kubectl apply`, `docker compose up` — Devin provisions and validates infrastructure
+- **Connect to remote systems** — SSH tunnels, VPN connections, database clients, API calls — Devin reaches private resources when given the right credentials
+- **Install what it needs** — Devin installs language runtimes, CLI tools, and dependencies on the fly. No pre-configured toolchain required (though you can configure persistent environments for faster startup)
+
+## Verification Model
+
+Devin is designed to verify its own work:
+
+1. **Local testing** — Devin runs unit tests, integration tests, linting, and type checking on its VM before opening a PR
+2. **CI monitoring** — After pushing, Devin watches CI checks and iterates if they fail. It reads CI logs, diagnoses failures, pushes fixes, and re-checks — up to multiple iterations
+3. **PR as the review gate** — Devin never merges its own work. It opens a PR, and humans (or Devin Review) inspect the diff before merging. The PR is the handoff point
+4. **External system validation** — Devin can connect to runners, staging environments, or external test systems to validate integration-level outcomes
+
+## Team Integration
+
+Devin operates as a team member, not a black box:
+
+- **Organizational configuration** — The shared context layer (environment configs, knowledge, playbooks, MCP servers, secrets, Git connections) applies to every session in the organization. One engineer configures it; every subsequent session benefits. See [Clean-Room Execution → Shared Context Layer](#shared-context-layer) above
+- **PR-based communication** — Multiple team members can comment on the same Devin PR. Devin reads all comments and responds to feedback from any reviewer
+- **Session continuity** — Devin hibernates its VM after inactivity and resumes from the hibernated state when new feedback arrives. Context is preserved across the full lifecycle of a task
+- **Audit trail** — Every session has a full log of actions, decisions, and outputs. Nothing is opaque