@ema.co/mcp-toolkit 1.5.1 → 1.6.0

package/docs/release-process.md

@@ -0,0 +1,153 @@
+# Release Process
+
+## Lessons Learned (2026-01-16)
+
+The `feat/v1.5.0-intelligence-layer` branch was orphaned for weeks, containing 5,600+ lines of code that diverged significantly from main. This document establishes processes to prevent similar situations.
+
+## Branch Hygiene Rules
+
+### 1. No Long-Lived Feature Branches
+
+**Rule:** Feature branches should be merged or closed within **2 weeks**.
+
+**Why:** Long-lived branches diverge and become difficult to merge.
+
+**Process:**
+- If a feature takes longer than 2 weeks, break it into smaller PRs
+- If blocked, document why and set a reminder to revisit
+
+### 2. Pre-Branch Checklist
+
+Before creating a new feature branch:
+
+```bash
+# 1. Fetch latest and check for unmerged work
+git fetch origin
+git branch -r --no-merged main | grep -v HEAD
+
+# 2. If unmerged branches exist, decide:
+#    - Merge them first? OR
+#    - Explicitly abandon them?
+
+# 3. Start from latest main
+git checkout main
+git pull origin main
+git checkout -b feat/my-feature
+```
+
+### 3. Weekly Stale Branch Review
+
+Run weekly to identify abandoned branches:
+
+```bash
+# Show branches not merged to main, sorted by age
+git for-each-ref --sort=committerdate refs/remotes/origin \
+  --format='%(committerdate:short) %(refname:short)' | \
+  grep -v HEAD | grep -v main
+```
+
+### 4. Post-Merge Cleanup
+
+After merging a PR:
+
+```bash
+# Delete the remote branch
+git push origin --delete feat/my-feature
+
+# Delete local branch
+git branch -d feat/my-feature
+
+# Verify cleanup
+git remote prune origin
+```
+
+## Version Bumping Strategy
+
+### Semantic Versioning
+
+| Change Type | Version Bump | Example |
+|-------------|--------------|---------|
+| Breaking change | Major | 1.5.2 → 2.0.0 |
+| New feature | Minor | 1.5.2 → 1.6.0 |
+| Bug fix | Patch | 1.5.2 → 1.5.3 |
+
+### Branch Naming Convention
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature | `feat/descriptive-name` | `feat/intelligence-layer-additive` |
+| Fix | `fix/descriptive-name` | `fix/fallback-detection` |
+| Release | `release/vX.Y.Z` | `release/v1.6.0` |
+
+### Pre-Release Checklist
+
+Before creating a release:
+
+1. **Check for unmerged work:**
+   ```bash
+   git branch -r --no-merged main
+   ```
+
+2. **Run full test suite:**
+   ```bash
+   npm run build && npm test
+   ```
+
+3. **Review CHANGELOG:**
+   - Are all changes documented?
+   - Is the version number correct?
+
+4. **Create release branch:**
+   ```bash
+   git checkout -b release/v1.6.0
+   # Update version in package.json
+   git commit -am "chore: release v1.6.0"
+   ```
+
+## Conflict Prevention
+
+### When Parallel Work Happens
+
+If two features are being developed in parallel:
+
+1. **Communicate:** Let the team know what you're working on
+2. **Small PRs:** Merge frequently to reduce divergence
+3. **Rebase often:** Keep feature branches up to date with main
+
+```bash
+# Rebase feature branch on latest main
+git fetch origin
+git rebase origin/main
+```
+
+### When Merging a Large Feature
+
+For large features (>500 lines):
+
+1. **Create a tracking issue** documenting what's being added
+2. **Break into reviewable chunks** (≤300 lines per PR)
+3. **Merge incrementally** rather than one giant PR
+
+## Automation (Future)
+
+Consider adding GitHub Actions for:
+
+1. **Stale branch alerts:** Weekly notification of branches >14 days old
+2. **PR size warnings:** Flag PRs with >500 lines changed
+3. **Unmerged branch check:** CI fails if important branches are unmerged before release
+
+## Quick Reference
+
+```bash
+# Check for unmerged branches
+git branch -r --no-merged main | grep -v HEAD
+
+# Compare branch to main
+git log main..origin/feat/branch-name --oneline
+git diff --stat main...origin/feat/branch-name
+
+# Clean up after merge
+git push origin --delete feat/branch-name
+git branch -d feat/branch-name
+git remote prune origin
+```

package/docs/test-persona-creation.md

@@ -0,0 +1,196 @@
+# Persona Creation Test Guide
+
+This guide tests the workflow tool's ability to create and configure AI Employees (personas).
+
+## Architecture
+
+### Greenfield (New Personas)
+1. **Create** persona from template (provides valid workflow structure)
+2. **Fetch** the created persona (get template's structure)
+3. **Update** proto_config only (voice settings, welcome message, etc.)
+4. **Customize workflow later** via modify mode if needed
+
+### Brownfield (Existing Personas)
+1. **Fetch** existing persona and workflow
+2. **Decompile** workflow_def → WorkflowSpec (typed representation)
+3. **Transform** spec based on user intent (LLM-native)
+4. **Compile** back to workflow_def
+5. **Update** persona with transformed workflow
+
+## Prerequisites
+
+1. **Rebuild the code**: 
+   ```bash
+   cd /path/to/ema-mcp-toolkit
+   npm run build
+   ```
+
+2. **Restart the MCP server** (Cursor caches code):
+   - `Cmd+Shift+P` → "Developer: Reload Window"
+
+3. Access to Ema dev environment
+
+---
+
+## Test Cases
+
+### Test 1: Create Voice AI Employee (Greenfield)
+
+**Goal:** Create a new Voice AI persona from template with configured settings.
+
+**Command:**
+```
+workflow(
+  input="Voice AI sales development representative for Ema. Handles discovery calls, qualifies prospects, explains value propositions.",
+  name="SP-TEST-VOICE-GREENFIELD",
+  type="voice",
+  preview=false,
+  env="dev"
+)
+```
+
+**Expected Result:**
+- `status: "deployed"`
+- `deployed_to.created: true`
+- `deployed_to.persona_id` returned
+- `next_steps` explains how to customize workflow
+
+**Verify:**
+```
+persona(id="<persona_id>", include_workflow=true, env="dev")
+```
+
+**Check:**
+- [ ] Persona exists with correct name
+- [ ] `proto_config.widgets` contains `conversationSettings` with:
+  - [ ] `welcomeMessage` - generated greeting
+  - [ ] `identityAndPurpose` - from description
+- [ ] `workflow_def` has template workflow (trigger node + possibly more from template)
+
+---
+
+### Test 2: Create Chat AI Employee (Greenfield)
+
+**Command:**
+```
+workflow(
+  input="IT helpdesk chatbot that answers employee questions about password resets, VPN setup, and software installation.",
+  name="SP-TEST-CHAT-GREENFIELD",
+  type="chat",
+  preview=false,
+  env="dev"
+)
+```
+
+**Expected Result:**
+- `status: "deployed"`
+- `deployed_to.created: true`
+
+**Verify:**
+```
+persona(id="<persona_id>", include_workflow=true, env="dev")
+```
+
+---
+
+### Test 3: Modify Existing Workflow (Brownfield)
+
+**Prerequisites:** Create a persona first (Test 1 or 2).
+
+**Goal:** Add functionality to an existing persona's workflow.
+
+**Command:**
+```
+workflow(
+  persona_id="<persona_id_from_test_1>",
+  input="add a search node that queries the knowledge base before responding",
+  preview=true,
+  env="dev"
+)
+```
+
+**Expected Result:**
+- `mode: "modify"`
+- Shows proposed changes
+- `modified_workflow` with new nodes
+
+**Deploy the changes:**
+```
+workflow(
+  persona_id="<persona_id>",
+  input="add a search node that queries the knowledge base before responding",
+  preview=false,
+  env="dev"
+)
+```
+
+---
+
+### Test 4: Analyze Workflow
+
+**Command:**
+```
+workflow(persona_id="<persona_id>", env="dev")
+```
+
+**Expected Result:**
+- `mode: "analyze"`
+- `issues` array (may be empty if healthy)
+- `metrics` with node_count, edge_count
+
+---
+
+### Test 5: Preview Only (No Deploy)
+
+**Goal:** Verify preview mode returns workflow without deploying.
+
+**Command:**
+```
+workflow(
+  input="Customer support voice AI that handles billing inquiries",
+  type="voice"
+)
+```
+
+**Expected Result:**
+- `status: "preview"`
+- `workflow_def` returned
+- `proto_config` with voice settings populated
+- NO persona created
+
+---
+
+## Cleanup
+
+After testing, delete test personas via the Ema UI or leave them for inspection.
+
+Test persona names:
+- SP-TEST-VOICE-GREENFIELD
+- SP-TEST-CHAT-GREENFIELD
+
+---
+
+## Troubleshooting
+
+### "Internal Server Error"
+- Usually means workflow format is wrong
+- Check if MCP server has latest code (restart Cursor)
+
+### "Widget name is empty"
+- Old code issue - restart MCP server
+
+### "Workflow name does not match"
+- Old code tried to replace workflow - now we don't touch workflow in greenfield
+
+### proto_config not updated
+- Check that greenfield flow only updates proto_config, not workflow
+- Widget merging should preserve template structure
+
+---
+
+## Key Code Locations
+
+- **Greenfield flow**: `src/mcp/handlers-consolidated.ts` (search for "GREENFIELD")
+- **Brownfield/modify flow**: `src/mcp/handlers-consolidated.ts` (search for "modify")
+- **Workflow transformer**: `src/sdk/workflow-transformer.ts` (decompile/compile)
+- **Proto config generation**: `src/sdk/workflow-generator.ts` (buildProtoConfig)