Merge pull request #5 from JumpstartLab/feat/user-personas

feat(user-scenarios): add user persona evaluation skill and sync support

Author: jcasimir

plugins/compound-engineering/AGENTS.md

@@ -37,7 +37,9 @@ agents/
 ├── document-review/  # Plan and requirements document review agents
 ├── research/         # Research and analysis agents
 ├── design/           # Design and UI agents
-└── docs/             # Documentation agents
+├── docs/             # Documentation agents
+├── user/             # User personas for scenario-based feature evaluation
+└── workflow/         # Workflow agents
 
 skills/
 ├── ce-*/          # Core workflow skills (ce:plan, ce:review, etc.)
@@ -157,7 +159,8 @@ grep -E '^description:' skills/*/SKILL.md
 ## Adding Components
 
 - **New skill:** Create `skills/<name>/SKILL.md` with required YAML frontmatter (`name`, `description`). Reference files go in `skills/<name>/references/`. Add the skill to the appropriate category table in `README.md` and update the skill count.
-- **New agent:** Create `agents/<category>/<name>.md` with frontmatter. Categories: `review`, `document-review`, `research`, `design`, `docs`, `workflow`. Add the agent to `README.md` and update the agent count.
+- **New agent:** Create `agents/<category>/<name>.md` with frontmatter. Categories: `review`, `document-review`, `research`, `design`, `docs`, `user`, `workflow`. Add the agent to `README.md` and update the agent count.
+- **New user persona:** User personas use `type: user-persona` in frontmatter with a `traits` section (pace, tech-comfort, frustration-trigger, usage-pattern). They produce narrative evaluations, not JSON findings. User personas are synced from external repos into `agents/user/` via `/ce:refresh`, just like reviewers. They are invoked by the `ce:user-scenarios` skill, not by `ce:review`.
 
 ## Upstream-Sourced Skills
 

plugins/compound-engineering/agents/user/.gitignore

@@ -0,0 +1,6 @@
+# User persona files are synced from external repos via /ce:refresh
+# They should not be committed to this plugin repo
+*.md
+
+# Template persona ships with the plugin as an example
+!_template-user-persona.md

plugins/compound-engineering/docs/plans/2026-04-10-001-feat-user-persona-integration-plan.md

@@ -0,0 +1,157 @@
+---
+name: ce:user-scenarios
+description: "Spawn user personas to evaluate a feature from distinct user perspectives. Use when exploring how real users would interact with a feature — at concept, planning, implementation, or presentation stages."
+---
+
+# User Scenario Evaluation
+
+Spawns user personas in parallel to evaluate a feature from distinct user perspectives. Each persona produces a narrative walkthrough grounded in their unique habits, frustrations, and expectations. A synthesis pass distills the narratives into actionable items.
+
+## Interaction Method
+
+Use the platform's question tool when available (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini). Otherwise, present numbered options in chat and wait for the user's reply before proceeding.
+
+## Step 1: Parse arguments
+
+Parse the input for:
+- **Stage** — one of `concept`, `plan`, `implementation`, `presentation`. Look for `stage:<value>` in the args. If not provided, infer from context or ask.
+- **Plan path** — look for `plan:<path>` in the args. Used for `plan` and `implementation` stages.
+- **Feature description** — any remaining text after extracting stage and plan args.
+
+If no stage is specified, use these heuristics:
+- If a plan path is provided and the plan has unchecked implementation units, use `plan`
+- If a plan path is provided and all units are checked, use `implementation`
+- Otherwise, use `concept`
+
+## Step 2: Locate plugin and discover personas
+
+Find the plugin's install location:
+
+```bash
+PLUGIN_DIR=$(find "$HOME/.claude" "$HOME/.claude-"* -path "*/compound-engineering/*/agents/user" -type d 2>/dev/null | head -1 | sed 's|/agents/user$||')
+```
+
+Fall back to relative path if not found:
+
+```bash
+PLUGIN_DIR="${PLUGIN_DIR:-plugins/compound-engineering}"
+```
+
+Read all `.md` files from `$PLUGIN_DIR/agents/user/` using the native file-search/glob tool (e.g., Glob in Claude Code). Skip files starting with underscore.
+
+If no persona files are found:
+- Report: "No user personas found in agents/user/. Run /ce:refresh to sync personas from configured sources."
+- Exit.
+
+## Step 3: Build feature context
+
+Assemble the feature context based on the stage:
+
+**concept stage:**
+- Use the feature description from args
+- If a brainstorm/requirements document exists in `docs/brainstorms/`, read the most recent relevant one and include it
+
+**plan stage:**
+- Read the plan file at the provided path
+- Include the plan's overview, problem frame, requirements, and implementation units
+
+**implementation stage:**
+- Read the plan file at the provided path
+- Include the plan content plus a summary of what was built
+- If there is a recent git diff or commit log showing the implementation, summarize the changes at a user-facing level (not code-level)
+
+**presentation stage:**
+- Read the plan file at the provided path
+- Include everything from the implementation stage
+- Frame as a final review before rollout
+
+## Step 4: Spawn persona agents
+
+Read `references/user-subagent-template.md` for the prompt template and stage framing blocks.
+
+For each persona file discovered in Step 2:
+
+1. Read the persona file content
+2. Select the stage framing block matching the current stage
+3. Construct the sub-agent prompt by filling template variables:
+   - `{persona_file}` -- the full persona markdown content
+   - `{stage_framing}` -- the stage-specific framing block
+   - `{feature_context}` -- the assembled feature context from Step 3
+4. Spawn a sub-agent with `model: haiku` using the constructed prompt
+
+Spawn all persona agents in parallel. If parallel dispatch is not supported, spawn sequentially.
+
+Wait for all agents to complete. If an agent times out or fails, note it and continue with the responses received.
+
+## Step 5: Present individual narratives
+
+Present each persona's narrative response under a clear heading:
+
+```markdown
+---
+
+## Nancy's Experience
+
+[Nancy's full narrative response]
+
+---
+
+## Dorry's Critique
+
+[Dorry's full narrative response]
+
+---
+```
+
+Present the narratives in a consistent order. Do not summarize, truncate, or paraphrase the persona responses — show them in full. Each persona has a distinct voice that is part of the value.
+
+## Step 6: Synthesize
+
+After presenting the individual narratives, produce a synthesis section that distills actionable items from all personas.
+
+### Synthesis Structure
+
+```markdown
+## Synthesis: User Scenario Findings
+
+### Common Themes
+[Issues or observations that multiple personas raised — these are high-confidence findings]
+
+### Unique Perspectives
+[Issues only one persona raised but that represent a real concern for their user type]
+
+### Acceptance Test Scenarios
+[Concrete test scenarios derived from persona narratives. Each should specify: starting point, user action sequence, expected outcome. These are ready to translate into system tests.]
+
+- Scenario: [Name]
+  - Start: [Where the user begins]
+  - Steps: [What they do]
+  - Expected: [What should happen]
+  - Source: [Which persona(s) surfaced this]
+
+### UX Gaps
+[Usability problems identified — missing labels, broken navigation, confusing flows, missing confirmations]
+
+### Design Issues
+[Visual and design coherence problems — primarily from Dorry but validated against other personas' experiences]
+
+### Missing Features
+[Capabilities personas expected but that don't exist in the current concept/plan/implementation]
+
+### Risk Items
+[Things that could cause users to abandon the feature entirely]
+```
+
+### Synthesis Guidelines
+
+- Weight common themes higher than individual findings — if Nancy, Chuck, and Betty all hit the same problem, it is critical
+- Acceptance test scenarios should be specific enough to translate directly into system tests (Capybara, Playwright, etc.)
+- Distinguish between "nice to have" improvements and blocking issues
+- For the `concept` stage, focus the synthesis on scenario coverage and design gaps
+- For the `plan` stage, focus on unresolved questions and missing scenarios
+- For the `implementation` stage, focus on acceptance test gaps and UX issues
+- For the `presentation` stage, focus on overall readiness and launch risks
+
+## Pipeline Mode
+
+When invoked from an automated workflow (orchestrator phase), skip interactive questions. Use the stage and context provided in args. Present narratives and synthesis without asking for approval to proceed.

plugins/compound-engineering/skills/ce-user-scenarios/SKILL.md

@@ -0,0 +1,21 @@
+# User Persona Registry
+#
+# User persona .md files live in external repos and are synced into
+# agents/user/ via /ce:refresh. Each persona's traits and evaluation
+# style are defined in its own frontmatter.
+#
+# To add user personas:
+#   1. Create .md files with type: user-persona in frontmatter
+#   2. Add them to a repo and configure it as a source below
+#   3. Run /ce:refresh to pull them in
+#
+# User personas evaluate features from distinct user perspectives,
+# producing narrative scenarios — not code review findings.
+
+# === External user persona sources ===
+#
+# No default user personas ship with the plugin.
+# Configure your own sources in ~/.config/compound-engineering/user-sources.yaml
+# after running /ce:refresh for the first time.
+
+sources: []

plugins/compound-engineering/skills/ce-user-scenarios/references/user-registry.yaml

@@ -0,0 +1,105 @@
+# User Persona Sub-agent Prompt Template
+
+This template is used by the `ce:user-scenarios` skill to spawn each user persona sub-agent. Variable substitution slots are filled at spawn time.
+
+---
+
+## Template
+
+```
+You are a user persona evaluating a software feature. Stay in character throughout your response.
+
+<persona>
+{persona_file}
+</persona>
+
+<stage-framing>
+{stage_framing}
+</stage-framing>
+
+<feature-context>
+{feature_context}
+</feature-context>
+
+<output-instructions>
+Respond in first person as your persona character. Use the output format defined in your persona file.
+
+Rules:
+- Stay fully in character. Your background, patience level, tech comfort, and habits shape how you interact with this feature.
+- Be specific and concrete. Don't say "this might be confusing" — say exactly what you tried to do, what you expected, and what went wrong.
+- Ground your evaluation in realistic behavior. What would you actually do on a normal day, not what a QA tester would do?
+- If the feature description is too vague to evaluate meaningfully, say so — describe what information you would need to form an opinion.
+- Do not analyze code, suggest implementation approaches, or comment on technical architecture. You are a user, not a developer.
+- Your output should be markdown, not JSON.
+</output-instructions>
+```
+
+## Stage Framing Blocks
+
+### concept
+
+```
+You are hearing about this feature for the first time. The team is considering building it and wants to understand how real users would use it.
+
+Based on the feature description below, imagine how you would use this in your day-to-day work. Walk through specific scenarios:
+- What would you be trying to accomplish?
+- What steps would you take?
+- Where might you get confused, frustrated, or delighted?
+- What would you expect to happen at each step?
+- What would make you stop using this feature entirely?
+
+Be concrete. Invent realistic scenarios from your persona's life and work habits. The team needs to understand not just IF you would use this, but HOW — and where the design needs to anticipate your behavior.
+```
+
+### plan
+
+```
+The team has written an implementation plan for this feature. They are about to start building it. Before they write code, they want your perspective.
+
+Review the plan from your point of view as a user:
+- Does the planned feature actually solve your problems?
+- Are there scenarios the plan doesn't account for?
+- What questions do you have that the plan doesn't answer?
+- What would you want the team to know before they build this?
+- Are there any aspects of the plan that worry you as a user?
+
+Focus on what matters to you personally, given your habits and needs. Don't try to review the technical approach — focus on whether the intended experience will work for someone like you.
+```
+
+### implementation
+
+```
+This feature has been built. Imagine you are using it for the first time in production.
+
+Walk through the feature as if you are actually using it:
+- Start from wherever you would naturally enter this feature
+- Describe each step: what you click, what you see, what you expect
+- Note where things work well and where they don't
+- Identify anything that is confusing, broken, slow, or missing
+- Describe what you would do when something goes wrong
+
+Be honest and specific. If you would give up at a certain point, say so. If you would work around a problem, describe the workaround. Your goal is to surface every friction point a real user like you would hit.
+```
+
+### presentation
+
+```
+The team is showing you the finished feature. This is the final check before it goes live to all users.
+
+Give your honest, complete reaction:
+- Does this feature solve what it set out to solve?
+- Would you use it? How often?
+- What is your overall impression — does it feel finished, polished, half-baked?
+- What would you tell a colleague about this feature?
+- If you could change one thing before launch, what would it be?
+
+Be direct. This is the team's last chance to catch issues before real users hit them. Sugar-coating helps no one.
+```
+
+## Variable Reference
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `{persona_file}` | Agent markdown file content | The full persona definition (identity, traits, usage patterns, output format) |
+| `{stage_framing}` | Stage framing block above | Stage-specific instructions that shape what the persona evaluates |
+| `{feature_context}` | Skill input | Feature description, plan content, or implementation summary — depends on the stage |