feat: Cognition Platform story — general themes + workshop delivery variants#109
feat: Cognition Platform story — general themes + workshop delivery variants#109devin-ai-integration[bot] wants to merge 2 commits into
Conversation
…ions - New general theme: cognition-platform.md covering Devin Desktop (IDE + agent manager), Devin CLI (terminal agent via cli.devin.ai), Devin Cloud (autonomous VM), ACP (Agent Client Protocol), and the platform continuum - Updated general themes README to reference the new platform doc - New shared/WORKSHOP-VARIANTS.md defining the .md / .platform.md / .local.md suffix conventions for workshop delivery surfaces
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| # Workshop Variant Conventions | ||
|
|
||
| Workshop content can target different delivery surfaces of the Cognition Platform. The file suffix indicates which surface(s) a workshop is written for. | ||
|
|
||
| ## File Suffixes | ||
|
|
||
| | Suffix | Surface | Participant Uses | Example | | ||
| |--------|---------|-----------------|---------| | ||
| | `.md` | **Devin Cloud only** | Cloud agent sessions via the Devin web app (app.devin.ai). All interaction through the browser: paste prompts, review PRs, leave comments | `README.md` | | ||
| | `.platform.md` | **Devin Desktop + Cloud** | Devin Desktop as the primary interface. Participants delegate tasks to Cloud from Desktop, review PRs in-editor, use the Agent Command Center and Spaces. Shows the full local→cloud→review loop | `README.platform.md` | | ||
| | `.local.md` | **Devin CLI / Devin Local only** | Terminal-based (Devin CLI) or Devin Local in Desktop. All work happens on the participant's local machine — no cloud VM sessions. For quick iterations, code exploration, and local-first workflows | `README.local.md` | | ||
|
|
||
| ## Which Suffix to Use | ||
|
|
||
| ### `README.md` (Cloud Agent) | ||
| Use when the workshop is designed for participants interacting with Devin's cloud agent through the web interface: | ||
| - Participants paste prompts into the Devin web app | ||
| - Devin works autonomously on a remote VM | ||
| - Output is a PR that participants review on GitHub/GitLab | ||
| - The full PR feedback loop (comment → iterate → approve → merge) is the primary interaction model | ||
| - Scheduled sessions, child agents, automations, and playbooks are all cloud features | ||
|
|
||
| **Platform story to weave in:** Even in cloud-only workshops, reference that the PRs Devin opens can be one-click checked out in Devin Desktop. Mention that teams typically manage multiple cloud sessions from the Agent Command Center. Note that the same playbooks and knowledge that power cloud sessions are also available to local agents. | ||
|
|
||
| ### `README.platform.md` (Desktop + Cloud) | ||
| Use when the workshop demonstrates the full platform continuum: | ||
| - Participants use Devin Desktop as their primary environment | ||
| - They create Spaces to organize work | ||
| - They delegate tasks to Cloud from Desktop and monitor progress in the Agent Command Center | ||
| - They review cloud-generated PRs directly in the editor (one-click checkout) | ||
| - They may also use Cascade or Devin Local for quick local tasks alongside cloud work | ||
| - The narrative emphasizes the handoff between local exploration and cloud execution | ||
|
|
||
| **Platform story to weave in:** This IS the platform story. Show the full loop: explore locally → refine requirements → delegate to Cloud → monitor in Kanban → review in editor → iterate → merge. Reference ACP and the ability to use multiple agents. Highlight Spaces as the organizational unit. | ||
|
|
||
| ### `README.local.md` (CLI / Devin Local) | ||
| Use when the workshop is designed for terminal-native or local-first workflows: | ||
| - Participants run `devin` in their terminal or use Devin Local in Desktop | ||
| - All code changes happen on their local machine | ||
| - No cloud VMs or remote sessions are involved | ||
| - Ideal for: code exploration, quick prototyping, rapid iteration, pair-programming style work | ||
| - Subagents handle parallel subtasks locally | ||
|
|
||
| **Platform story to weave in:** Note that tasks can be handed off to Cloud when they outgrow local execution. Mention that Devin CLI is consumable over ACP inside Devin Desktop. Reference that the same skills and MCP servers work across all surfaces. | ||
|
|
||
| ## Coexistence Rules | ||
|
|
||
| 1. **Every workshop directory MUST have a `README.md`** — the cloud-agent variant is the baseline | ||
| 2. Additional variants (`.platform.md`, `.local.md`) are optional and created when the workshop content genuinely benefits from a surface-specific narrative | ||
| 3. Variants are not copies with find-and-replace edits — each should be written for its delivery surface with appropriate prompts, workflow steps, and platform context | ||
| 4. All variants share the same lab structure (tracks, lab numbering) for cross-referencing | ||
| 5. The `README.md` variant should mention the existence of other variants at the top if they exist | ||
|
|
||
| ## Platform Context Sections | ||
|
|
||
| Every workshop variant (regardless of suffix) should include a section near the top called **"Platform Context"** that briefly explains which Cognition Platform surfaces are used and how they connect. Template: | ||
|
|
||
| ```markdown | ||
| ## Platform Context | ||
|
|
||
| This workshop uses **[surface(s)]**. [1-2 sentences on the workflow]. | ||
|
|
||
| > **Tip:** [One sentence connecting to other surfaces for participants who want to explore further] | ||
| ``` | ||
|
|
||
| ## Cross-Surface References | ||
|
|
||
| When a workshop variant references capabilities from another surface, use callout blocks: | ||
|
|
||
| ```markdown | ||
| > **Desktop tip:** The PRs Devin opens in this lab can be reviewed directly in Devin Desktop | ||
| > with one-click checkout — no manual `git fetch` required. | ||
| ``` | ||
|
|
||
| ```markdown | ||
| > **Cloud handoff:** If this task needs long-running autonomous execution, you can hand it | ||
| > off to Devin Cloud. The cloud agent picks up where your local session left off. | ||
| ``` | ||
|
|
||
| ```markdown | ||
| > **CLI alternative:** This same task can be run from your terminal with `devin`. See the | ||
| > `.local.md` variant of this workshop for the terminal-native workflow. | ||
| ``` |
There was a problem hiding this comment.
🚩 WORKSHOP-VARIANTS.md may be author-facing rather than attendee-facing content
The shared/WORKSHOP-VARIANTS.md file describes conventions for how to name and organize workshop files — file suffix rules, coexistence rules, "Platform story to weave in" guidance (lines 23, 34, 44), and template snippets for content authors. This reads as a contributor/authoring guide rather than attendee-facing material. The REVIEW.md rule says "This entire repo is for attendees. Flag any facilitator-only content." However, the specific examples listed (MCP setup, presales positioning, timing guides, pacing tips, post-event checklists) don't clearly cover content-authoring conventions. Files like REVIEW.md and AGENTS.md are themselves non-attendee content at the repo root, so there's precedent for meta-documentation. The "Platform story to weave in" sections (e.g., shared/WORKSHOP-VARIANTS.md:23) are the closest to facilitator guidance, as they tell authors how to position platform features in their content. This is borderline — not clearly a rule violation, but worth the reviewer confirming whether this file belongs here or in the operator repo.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Good catch — this is intentionally author-facing guidance (like AGENTS.md itself). It lives in shared/ because the child agents and future content authors need it in-repo to follow the convention when creating variants. Happy to move it to operator if you'd prefer, but keeping it here alongside AGENTS.md ensures the convention is discoverable where the content lives.
| # Workshop Variant Conventions | ||
|
|
||
| Workshop content can target different delivery surfaces of the Cognition Platform. The file suffix indicates which surface(s) a workshop is written for. | ||
|
|
||
| ## File Suffixes | ||
|
|
||
| | Suffix | Surface | Participant Uses | Example | | ||
| |--------|---------|-----------------|---------| | ||
| | `.md` | **Devin Cloud only** | Cloud agent sessions via the Devin web app (app.devin.ai). All interaction through the browser: paste prompts, review PRs, leave comments | `README.md` | | ||
| | `.platform.md` | **Devin Desktop + Cloud** | Devin Desktop as the primary interface. Participants delegate tasks to Cloud from Desktop, review PRs in-editor, use the Agent Command Center and Spaces. Shows the full local→cloud→review loop | `README.platform.md` | | ||
| | `.local.md` | **Devin CLI / Devin Local only** | Terminal-based (Devin CLI) or Devin Local in Desktop. All work happens on the participant's local machine — no cloud VM sessions. For quick iterations, code exploration, and local-first workflows | `README.local.md` | | ||
|
|
||
| ## Which Suffix to Use | ||
|
|
||
| ### `README.md` (Cloud Agent) | ||
| Use when the workshop is designed for participants interacting with Devin's cloud agent through the web interface: | ||
| - Participants paste prompts into the Devin web app | ||
| - Devin works autonomously on a remote VM | ||
| - Output is a PR that participants review on GitHub/GitLab | ||
| - The full PR feedback loop (comment → iterate → approve → merge) is the primary interaction model | ||
| - Scheduled sessions, child agents, automations, and playbooks are all cloud features | ||
|
|
||
| **Platform story to weave in:** Even in cloud-only workshops, reference that the PRs Devin opens can be one-click checked out in Devin Desktop. Mention that teams typically manage multiple cloud sessions from the Agent Command Center. Note that the same playbooks and knowledge that power cloud sessions are also available to local agents. | ||
|
|
||
| ### `README.platform.md` (Desktop + Cloud) | ||
| Use when the workshop demonstrates the full platform continuum: | ||
| - Participants use Devin Desktop as their primary environment | ||
| - They create Spaces to organize work | ||
| - They delegate tasks to Cloud from Desktop and monitor progress in the Agent Command Center | ||
| - They review cloud-generated PRs directly in the editor (one-click checkout) | ||
| - They may also use Cascade or Devin Local for quick local tasks alongside cloud work | ||
| - The narrative emphasizes the handoff between local exploration and cloud execution | ||
|
|
||
| **Platform story to weave in:** This IS the platform story. Show the full loop: explore locally → refine requirements → delegate to Cloud → monitor in Kanban → review in editor → iterate → merge. Reference ACP and the ability to use multiple agents. Highlight Spaces as the organizational unit. | ||
|
|
||
| ### `README.local.md` (CLI / Devin Local) | ||
| Use when the workshop is designed for terminal-native or local-first workflows: | ||
| - Participants run `devin` in their terminal or use Devin Local in Desktop | ||
| - All code changes happen on their local machine | ||
| - No cloud VMs or remote sessions are involved | ||
| - Ideal for: code exploration, quick prototyping, rapid iteration, pair-programming style work | ||
| - Subagents handle parallel subtasks locally | ||
|
|
||
| **Platform story to weave in:** Note that tasks can be handed off to Cloud when they outgrow local execution. Mention that Devin CLI is consumable over ACP inside Devin Desktop. Reference that the same skills and MCP servers work across all surfaces. | ||
|
|
||
| ## Coexistence Rules | ||
|
|
||
| 1. **Every workshop directory MUST have a `README.md`** — the cloud-agent variant is the baseline | ||
| 2. Additional variants (`.platform.md`, `.local.md`) are optional and created when the workshop content genuinely benefits from a surface-specific narrative | ||
| 3. Variants are not copies with find-and-replace edits — each should be written for its delivery surface with appropriate prompts, workflow steps, and platform context | ||
| 4. All variants share the same lab structure (tracks, lab numbering) for cross-referencing | ||
| 5. The `README.md` variant should mention the existence of other variants at the top if they exist | ||
|
|
||
| ## Platform Context Sections | ||
|
|
||
| Every workshop variant (regardless of suffix) should include a section near the top called **"Platform Context"** that briefly explains which Cognition Platform surfaces are used and how they connect. Template: | ||
|
|
||
| ```markdown | ||
| ## Platform Context | ||
|
|
||
| This workshop uses **[surface(s)]**. [1-2 sentences on the workflow]. | ||
|
|
||
| > **Tip:** [One sentence connecting to other surfaces for participants who want to explore further] | ||
| ``` | ||
|
|
||
| ## Cross-Surface References | ||
|
|
||
| When a workshop variant references capabilities from another surface, use callout blocks: | ||
|
|
||
| ```markdown | ||
| > **Desktop tip:** The PRs Devin opens in this lab can be reviewed directly in Devin Desktop | ||
| > with one-click checkout — no manual `git fetch` required. | ||
| ``` | ||
|
|
||
| ```markdown | ||
| > **Cloud handoff:** If this task needs long-running autonomous execution, you can hand it | ||
| > off to Devin Cloud. The cloud agent picks up where your local session left off. | ||
| ``` | ||
|
|
||
| ```markdown | ||
| > **CLI alternative:** This same task can be run from your terminal with `devin`. See the | ||
| > `.local.md` variant of this workshop for the terminal-native workflow. | ||
| ``` |
There was a problem hiding this comment.
🟡 WORKSHOP-VARIANTS.md is content-author/facilitator guidance placed in an attendee-facing repo
REVIEW.md mandates: "This entire repo is for attendees. Flag any facilitator-only content (MCP setup, presales positioning, timing guides, pacing tips for facilitators, post-event checklists). These belong in the operator repo."
shared/WORKSHOP-VARIANTS.md is entirely content-authoring guidance targeted at workshop creators, not at workshop attendees. It contains file-suffix naming conventions ("Which Suffix to Use"), authoring instructions ("Platform story to weave in: Even in cloud-only workshops, reference that…" at lines 23, 34, 44), coexistence rules for variant management (line 46–52), and Markdown templates for authors to copy into their workshops (lines 54–64). An attendee following a workshop would never need to know which file suffix to use or what narrative to "weave in." This is facilitator/content-author guidance that belongs in the operator repo per the content separation rule.
Prompt for agents
The entire file shared/WORKSHOP-VARIANTS.md is content-authoring guidance (file-suffix conventions, 'Platform story to weave in' instructions, coexistence rules, authoring templates) aimed at workshop creators, not workshop attendees. Per REVIEW.md, this repo is exclusively for attendee-facing content; facilitator and content-author guidance belongs in the operator repo (https://github.com/Cognition-Partner-Workshops/operator). Move this file to the operator repo. If any subset of the information (e.g., explaining to attendees why multiple README variants exist) is genuinely attendee-facing, extract only that portion into a brief note in shared/ and keep the authoring conventions in operator.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Acknowledged — same concern as the previous review round. This file is intentionally author-facing guidance, similar to AGENTS.md at the repo root. It needs to live alongside the workshop content so child agents (and future authors) can reference it when creating variants. The "Platform story to weave in" sections are author instructions, not attendee content — this is the same category as AGENTS.md rules. Leaving for reviewer to confirm placement.
1 participant
Summary
Adds the full Cognition Platform narrative to general themes and establishes the workshop delivery-variant convention. This PR is the parent branch — child agent PRs will merge into this branch, each adding platform story coverage and
.platform.md/.local.mdvariants to individual workshop directories.New files:
shared/general-themes/cognition-platform.md— covers Devin Desktop (IDE + Agent Command Center + Spaces + one-click checkout), Devin CLI (cli.devin.ai, ACP-consumable, cloud handoff), Devin Cloud (autonomous VM), ACP protocol, and the platform continuum showing local→cloud transitionsshared/WORKSHOP-VARIANTS.md— defines file suffix conventions:.md= Cloud agent only (baseline).platform.md= Desktop + Cloud (delegate → monitor → review in editor).local.md= CLI / Devin Local only (terminal-native)Modified:
shared/general-themes/README.md— added the new platform doc to the index table.Child PRs (16 total): Each workshop directory gets a child agent that updates the existing
README.mdwith platform context callouts and creates delivery-surface variants. Those PRs target this branch.Link to Devin session: https://partner-workshops.devinenterprise.com/sessions/19cd0f209f4349ebbaba4c7fc7fef8a3
Requested by: @bsmitches