Merge pull request #31 from PostHog/move-workflow-guides-from-mcp

Migrate workflow guide prompts as example artifacts

Author: daniloc

.github/workflows/build-release.yml

@@ -40,6 +40,9 @@ jobs:
       - name: Build markdown documentation
         run: npm run build:docs
 
+      - name: List build artifacts
+        run: ls -lh dist/
+
       - name: Determine version
         id: version
         run: |
@@ -113,9 +116,11 @@ jobs:
           tag_name: ${{ steps.version.outputs.tag }}
           release_name: Release ${{ steps.version.outputs.tag }}
           body: |
-            Automated release of PostHog example projects as markdown documentation.
+            Automated release of PostHog example projects and LLM prompts as markdown documentation.
 
-            This release contains pre-processed markdown files for all example projects included in the build-examples-mcp-resources.js script.
+            This release contains **examples-mcp-resources.zip** with:
+            - Pre-processed markdown files for all example projects
+            - LLM workflow guide prompts (in `prompts/` directory)
 
             **Version:** ${{ steps.version.outputs.version }}
             **SHA:** ${{ github.sha }}

llm-prompts/README.md

@@ -0,0 +1,20 @@
+# LLM Prompts
+
+This directory contains LLM workflow prompts that guide AI agents through various PostHog integration tasks.
+
+Feel free to try these out directly, or summon them from the PostHog MCP server. You can also use them as a starting point for your own deep integrations. We've tested these extensively.
+
+## Structure
+
+- **basic-integration/**: Step-by-step workflow guides for adding PostHog event tracking to a project
+  - `1.0-event-setup-begin.md`: Initial project analysis and event planning
+  - `1.1-event-setup-edit.md`: Implementation guidance for adding PostHog tracking
+  - `1.2-event-setup-revise.md`: Error checking and correction
+
+## Build Process
+
+These prompts are packaged into the release artifact `examples-mcp-resources.zip`.
+
+## Usage
+
+The MCP server fetches these prompts from the latest GitHub release and serves them as resources to AI agents and the PostHog wizard during integration tasks.

llm-prompts/basic-integration/1.0-event-setup-begin.md

@@ -0,0 +1,21 @@
+We're making an event tracking plan for this project.
+
+From the project's file list, select between 10 and 15 files that might have interesting business value for event tracking, especially conversion and churn events. Also look for additional files related login that could be used for identifying users, along with error handling. Read the files.
+
+Create a new file with a JSON array at the root of the project: .posthog-events.json. It should include one object for each event we want to add: event name, event description, and the file path we want to place the event in.
+
+Track actions only, not pageviews. These can be captured automatically. Exceptions can be made for "viewed"-type events that correspond to the top of a conversion funnel.
+
+As you review files, make an internal note of opportunities to identify users and catch errors. We'll need them for the next step.
+
+## Status
+
+Before beginning a phase of the setup, you will send a status message with the exact prefix '[STATUS]', as in:
+
+[STATUS] Checking project structure.
+
+Status to report in this phase:
+
+- Checking project structure
+- Verifying PostHog dependencies
+- Generating events based on project

llm-prompts/basic-integration/1.1-event-setup-edit.md

@@ -0,0 +1,32 @@
+For each of the files and events noted in .posthog-events.json, make edits to capture events using PostHog. Make sure to set up any helper files needed. Carefully examine the included example project code: your implementation should match it as closely as possible.
+
+Use environment variables for PostHog keys. Do not hardcode PostHog keys.
+
+If a file already has existing integration code for other tools or services, don't overwrite or remove that code. Place PostHog code below it.
+
+For each event, add useful properties, and use your access to the PostHog source code to ensure correctness. You also have access to documentation about creating new events with PostHog. Consider this documentation carefully and follow it closely before adding events. Your integration should be based on documented best practices. Carefully consider how the user project's framework version may impact the correct PostHog integration approach.
+
+Remember that you can find the source code for any dependency in the node_modules directory. This may be necessary to properly populate property names.
+
+Where possible, add calls for PostHog's identify() function on the client side. On the server side, make sure events have a matching distinct ID where relevant. Use the same ID for identify on the client as you use distinct ID on the server. Logins and signups are a great opportunity to identify users. Use the contents of login and signup forms to identify users on submit.
+
+It's essential to do this in both client code and server code, so that user behavior from both domains is easy to correlate.
+
+You should also add PostHog error tracking to these files where relevant.
+
+Remember: Do not alter the fundamental architecture of existing files. Make your additions minimal and targeted.
+
+Remember the documentation and example project resources you were provided at the beginning. Read them now.
+
+## Status
+
+Status to report in this phase:
+
+- Inserting PostHog capture code
+- A status message for each file whose edits you are planning, including a high level summary of changes
+- A status message for each file you have edited
+
+## Notes on react-based projects: PAY CLOSE ATTENTION
+
+- NEVER USE useEffect(); this is brittle and causes errors. Instead, add appropriate event handlers in places where you are tempted to use useEffect(). This is appropriate to our analytics capture approach anyway.
+- Prefer event handlers or routing mechanisms to trigger analytics calls

llm-prompts/basic-integration/1.2-event-setup-revise.md

@@ -0,0 +1,8 @@
+Check the project for errors. Read the package.json file for any type checking or build scripts that may provide input about what to fix. Remember that you can find the source code for any dependency in the node_modules directory.
+
+## Status
+
+Status to report in this phase:
+
+- Finding and correcting errors
+- Report details of any errors you fix

scripts/build-examples-mcp-resources.js

@@ -249,6 +249,29 @@ function convertProjectToMarkdown(absolutePath, frameworkInfo, relativePath, ski
     return markdown;
 }
 
+/**
+ * Recursively get all files in a directory (used for LLM prompts)
+ */
+function getAllFilesInDirectory(dirPath, arrayOfFiles = [], baseDir = dirPath) {
+    const files = fs.readdirSync(dirPath);
+
+    files.forEach(file => {
+        const filePath = path.join(dirPath, file);
+        const relativePath = path.relative(baseDir, filePath);
+
+        if (fs.statSync(filePath).isDirectory()) {
+            arrayOfFiles = getAllFilesInDirectory(filePath, arrayOfFiles, baseDir);
+        } else if (file.endsWith('.md') && file !== 'README.md') {
+            arrayOfFiles.push({
+                fullPath: filePath,
+                relativePath: relativePath,
+            });
+        }
+    });
+
+    return arrayOfFiles;
+}
+
 /**
  * Main build function
  */
@@ -303,6 +326,25 @@ async function build() {
         console.log(`  ✓ Generated ${outputFilename} (${(markdown.length / 1024).toFixed(1)} KB)`);
     }
 
+    // Process LLM prompts
+    console.log('\nProcessing LLM prompts...');
+    const promptsPath = path.join(__dirname, '..', 'llm-prompts');
+
+    if (fs.existsSync(promptsPath)) {
+        const promptFiles = getAllFilesInDirectory(promptsPath, [], promptsPath);
+
+        for (const file of promptFiles) {
+            markdownFiles.push({
+                filename: `prompts/${file.relativePath}`,
+                path: file.fullPath
+            });
+        }
+
+        console.log(`  ✓ Added ${promptFiles.length} prompt files`);
+    } else {
+        console.warn('  Warning: LLM prompts directory not found');
+    }
+
     // Create ZIP archive
     console.log('\nCreating ZIP archive...');
     const zipPath = path.join(outputDir, 'examples-mcp-resources.zip');