feat: add general-themes narrative content with shared context layer improvements

shared/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 |

shared/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

shared/general-themes/collaboration-model.md

@@ -0,0 +1,111 @@
+# Collaboration Model
+
+Devin integrates into existing engineering workflows through pull requests, CI/CD pipelines, and team communication channels. It participates in the processes your team already uses — no new tools or workflows required.
+
+## The PR Feedback Loop
+
+The pull request is Devin's primary interface with human engineers. Every Devin implementation results in a PR that follows your team's existing review process.
+
+```
+Devin opens PR
+    ↓
+CI checks run automatically
+    ├── Pass → PR is ready for human review
+    └── Fail → Devin reads logs, pushes fix, CI re-runs
+          ↓
+Human reviewers inspect the diff
+    ├── Approve → Merge (human decision)
+    └── Request changes → Devin reads comments, iterates
+          ↓
+Devin pushes new commits addressing feedback
+    ↓
+CI re-runs → Review cycle repeats until approved
+```
+
+**Key properties:**
+- Devin **never merges its own PRs**. The merge decision is always human
+- CI serves as an automated quality gate. Devin iterates until CI passes or escalates if it cannot resolve the failure
+- PR comments are the communication channel. No special tools or interfaces required
+- The PR provides a complete audit trail of what Devin proposed and how it evolved through review
+
+## Multi-User Communication
+
+Multiple team members can interact with the same Devin session through PR comments:
+
+- **Reviewer A** comments: "This function should handle the null case"
+- **Reviewer B** comments: "Please add a test for the edge case in line 42"
+- Devin reads both comments, addresses both requests in subsequent commits
+- Both reviewers see Devin's response and can continue the conversation
+
+This works because Devin monitors its PRs for new comments. When any comment arrives, Devin resumes from its hibernated state and responds with its full conversation context retained — no re-reading from scratch. The session persists across the entire lifecycle of the task with no context loss between interactions.
+
+## CI Check Monitoring
+
+Devin actively monitors CI pipeline results after pushing code:
+
+1. **Watches for completion** — Devin polls CI status checks until all jobs complete
+2. **Reads failure logs** — When a check fails, Devin downloads and analyzes the CI job logs
+3. **Diagnoses the issue** — Devin identifies whether the failure is in its code, in the test environment, or in infrastructure
+4. **Pushes a fix** — For code-level failures, Devin commits a fix and waits for CI to re-run
+5. **Escalates if stuck** — After multiple failed attempts, Devin asks the user for help rather than looping indefinitely
+
+This creates a tight feedback loop where Devin iterates toward a green build without human intervention for straightforward failures.
+
+## Hibernation and Resume
+
+Devin sessions manage compute resources efficiently:
+
+- **Active work** — Devin is running on its VM, executing tasks, building code, running tests
+- **Waiting for feedback** — After opening a PR or asking a question, Devin enters a monitoring state
+- **Hibernation** — After inactivity, Devin snapshots its VM state and releases compute. The session appears idle but all context is preserved
+- **Resume** — When new input arrives (PR comment, CI result, user message), Devin restores its VM from the snapshot and continues exactly where it left off
+
+**What this means for users:**
+- You do not need to respond immediately. Devin waits patiently and resumes when you are ready
+- Sessions do not consume resources while waiting. Cost is proportional to active work time
+- Long-running tasks (multi-day code reviews, back-and-forth iterations) are natural. The session persists across the entire lifecycle
+
+## Working with Existing Tools
+
+Devin connects to your team's existing toolchain through MCP servers and API integrations:
+
+| Tool Category | Examples | How Devin Uses It |
+|---------------|----------|-------------------|
+| **Issue Trackers** | Jira, Linear, Azure DevOps | Read ticket details, update status, link PRs |
+| **Observability** | Datadog, New Relic, Azure Monitor | Query logs, traces, and metrics during incident investigation |
+| **Documentation** | Confluence, Notion | Read existing docs for context, update docs as part of implementation |
+| **Communication** | Slack, Microsoft Teams | Receive trigger messages, post status updates |
+| **Cloud Platforms** | AWS, Azure, GCP | Deploy resources, query infrastructure state, manage environments |
+| **Databases** | PostgreSQL, MySQL, MongoDB | Query schemas, run migrations, validate data integrity |
+
+These integrations are configured once at the organization level as part of Devin's shared context layer (see [Architecture Strengths → Shared Context Layer](architecture-strengths.md#shared-context-layer)) and are available to every session automatically.
+
+## Continuous Improvement Cycle
+
+Devin's effectiveness compounds over time as the team invests in the shared context layer:
+
+```
+Initial Setup
+    ├── Connect repos (Git connections)
+    ├── Configure environment (VM blueprints with runtimes, tools)
+    ├── Add knowledge notes (standards, conventions, domain glossary)
+    ├── Provision secrets (API keys, service account credentials)
+    └── Set up MCP servers (Jira, Datadog, Confluence, etc.)
+        ↓
+First Sessions
+    ├── Devin learns the codebase through context retrieval
+    ├── Team refines prompts based on results
+    └── Playbooks are created for recurring tasks
+        ↓
+Mature Operation
+    ├── Scheduled sessions handle routine O&M automatically
+    ├── Event-driven triggers respond to incidents and findings in real time
+    ├── Playbooks encode institutional knowledge for consistent execution
+    └── Child agents parallelize large-scale campaigns
+        ↓
+Compounding Value
+    ├── Less manual O&M overhead → engineers focus on architecture and product
+    ├── Faster incident response → reduced MTTR
+    ├── Consistent quality enforcement → fewer regressions
+    └── Scalable capacity → handle work surges without hiring
+```