Skip to content

Commit f52398b

Browse files
jcasimirclaude
jcasimir
and
claude
committed
feat(user-scenarios): add user persona evaluation skill and sync support
Introduce user personas as a new agent type that evaluates features from distinct user perspectives (Nancy, Dorry, Chuck, Betty, Mark). Unlike code reviewers that analyze diffs, user personas produce narrative walkthroughs grounded in their unique habits and frustrations. - Add agents/user/ directory with .gitignore for synced personas - Create ce:user-scenarios skill with four evaluation stages (concept, plan, implementation, presentation) - Add user-subagent-template with stage-specific framing blocks - Update ce:refresh to sync user personas alongside reviewers and orchestrators - Update AGENTS.md with user persona documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2c36199 commit f52398b

7 files changed

Lines changed: 652 additions & 13 deletions

File tree

‎plugins/compound-engineering/AGENTS.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,9 @@ agents/
3737
├── document-review/ # Plan and requirements document review agents
3838
├── research/ # Research and analysis agents
3939
├── design/ # Design and UI agents
40-
└── docs/ # Documentation agents
40+
├── docs/ # Documentation agents
41+
├── user/ # User personas for scenario-based feature evaluation
42+
└── workflow/ # Workflow agents
4143
4244
skills/
4345
├── ce-*/ # Core workflow skills (ce:plan, ce:review, etc.)
@@ -157,7 +159,8 @@ grep -E '^description:' skills/*/SKILL.md
157159
## Adding Components
158160

159161
- **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.
160-
- **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.
162+
- **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.
163+
- **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`.
161164

162165
## Upstream-Sourced Skills
163166

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# User persona files are synced from external repos via /ce:refresh
2+
# They should not be committed to this plugin repo
3+
*.md
4+
5+
# Template persona ships with the plugin as an example
6+
!_template-user-persona.md

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

Lines changed: 324 additions & 0 deletions
Large diffs are not rendered by default.

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

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
name: ce:user-scenarios
3+
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."
4+
---
5+
6+
# User Scenario Evaluation
7+
8+
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.
9+
10+
## Interaction Method
11+
12+
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.
13+
14+
## Step 1: Parse arguments
15+
16+
Parse the input for:
17+
- **Stage** — one of `concept`, `plan`, `implementation`, `presentation`. Look for `stage:<value>` in the args. If not provided, infer from context or ask.
18+
- **Plan path** — look for `plan:<path>` in the args. Used for `plan` and `implementation` stages.
19+
- **Feature description** — any remaining text after extracting stage and plan args.
20+
21+
If no stage is specified, use these heuristics:
22+
- If a plan path is provided and the plan has unchecked implementation units, use `plan`
23+
- If a plan path is provided and all units are checked, use `implementation`
24+
- Otherwise, use `concept`
25+
26+
## Step 2: Locate plugin and discover personas
27+
28+
Find the plugin's install location:
29+
30+
```bash
31+
PLUGIN_DIR=$(find "$HOME/.claude" "$HOME/.claude-"* -path "*/compound-engineering/*/agents/user" -type d 2>/dev/null | head -1 | sed 's|/agents/user$||')
32+
```
33+
34+
Fall back to relative path if not found:
35+
36+
```bash
37+
PLUGIN_DIR="${PLUGIN_DIR:-plugins/compound-engineering}"
38+
```
39+
40+
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.
41+
42+
If no persona files are found:
43+
- Report: "No user personas found in agents/user/. Run /ce:refresh to sync personas from configured sources."
44+
- Exit.
45+
46+
## Step 3: Build feature context
47+
48+
Assemble the feature context based on the stage:
49+
50+
**concept stage:**
51+
- Use the feature description from args
52+
- If a brainstorm/requirements document exists in `docs/brainstorms/`, read the most recent relevant one and include it
53+
54+
**plan stage:**
55+
- Read the plan file at the provided path
56+
- Include the plan's overview, problem frame, requirements, and implementation units
57+
58+
**implementation stage:**
59+
- Read the plan file at the provided path
60+
- Include the plan content plus a summary of what was built
61+
- If there is a recent git diff or commit log showing the implementation, summarize the changes at a user-facing level (not code-level)
62+
63+
**presentation stage:**
64+
- Read the plan file at the provided path
65+
- Include everything from the implementation stage
66+
- Frame as a final review before rollout
67+
68+
## Step 4: Spawn persona agents
69+
70+
Read `references/user-subagent-template.md` for the prompt template and stage framing blocks.
71+
72+
For each persona file discovered in Step 2:
73+
74+
1. Read the persona file content
75+
2. Select the stage framing block matching the current stage
76+
3. Construct the sub-agent prompt by filling template variables:
77+
- `{persona_file}` -- the full persona markdown content
78+
- `{stage_framing}` -- the stage-specific framing block
79+
- `{feature_context}` -- the assembled feature context from Step 3
80+
4. Spawn a sub-agent with `model: haiku` using the constructed prompt
81+
82+
Spawn all persona agents in parallel. If parallel dispatch is not supported, spawn sequentially.
83+
84+
Wait for all agents to complete. If an agent times out or fails, note it and continue with the responses received.
85+
86+
## Step 5: Present individual narratives
87+
88+
Present each persona's narrative response under a clear heading:
89+
90+
```markdown
91+
---
92+
93+
## Nancy's Experience
94+
95+
[Nancy's full narrative response]
96+
97+
---
98+
99+
## Dorry's Critique
100+
101+
[Dorry's full narrative response]
102+
103+
---
104+
```
105+
106+
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.
107+
108+
## Step 6: Synthesize
109+
110+
After presenting the individual narratives, produce a synthesis section that distills actionable items from all personas.
111+
112+
### Synthesis Structure
113+
114+
```markdown
115+
## Synthesis: User Scenario Findings
116+
117+
### Common Themes
118+
[Issues or observations that multiple personas raised — these are high-confidence findings]
119+
120+
### Unique Perspectives
121+
[Issues only one persona raised but that represent a real concern for their user type]
122+
123+
### Acceptance Test Scenarios
124+
[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.]
125+
126+
- Scenario: [Name]
127+
- Start: [Where the user begins]
128+
- Steps: [What they do]
129+
- Expected: [What should happen]
130+
- Source: [Which persona(s) surfaced this]
131+
132+
### UX Gaps
133+
[Usability problems identified — missing labels, broken navigation, confusing flows, missing confirmations]
134+
135+
### Design Issues
136+
[Visual and design coherence problems — primarily from Dorry but validated against other personas' experiences]
137+
138+
### Missing Features
139+
[Capabilities personas expected but that don't exist in the current concept/plan/implementation]
140+
141+
### Risk Items
142+
[Things that could cause users to abandon the feature entirely]
143+
```
144+
145+
### Synthesis Guidelines
146+
147+
- Weight common themes higher than individual findings — if Nancy, Chuck, and Betty all hit the same problem, it is critical
148+
- Acceptance test scenarios should be specific enough to translate directly into system tests (Capybara, Playwright, etc.)
149+
- Distinguish between "nice to have" improvements and blocking issues
150+
- For the `concept` stage, focus the synthesis on scenario coverage and design gaps
151+
- For the `plan` stage, focus on unresolved questions and missing scenarios
152+
- For the `implementation` stage, focus on acceptance test gaps and UX issues
153+
- For the `presentation` stage, focus on overall readiness and launch risks
154+
155+
## Pipeline Mode
156+
157+
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/references/user-registry.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# User Persona Registry
2+
#
3+
# User persona .md files live in external repos and are synced into
4+
# agents/user/ via /ce:refresh. Each persona's traits and evaluation
5+
# style are defined in its own frontmatter.
6+
#
7+
# To add user personas:
8+
# 1. Create .md files with type: user-persona in frontmatter
9+
# 2. Add them to a repo and configure it as a source below
10+
# 3. Run /ce:refresh to pull them in
11+
#
12+
# User personas evaluate features from distinct user perspectives,
13+
# producing narrative scenarios — not code review findings.
14+
15+
# === External user persona sources ===
16+
#
17+
# No default user personas ship with the plugin.
18+
# Configure your own sources in ~/.config/compound-engineering/user-sources.yaml
19+
# after running /ce:refresh for the first time.
20+
21+
sources: []

‎plugins/compound-engineering/skills/ce-user-scenarios/references/user-subagent-template.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# User Persona Sub-agent Prompt Template
2+
3+
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.
4+
5+
---
6+
7+
## Template
8+
9+
```
10+
You are a user persona evaluating a software feature. Stay in character throughout your response.
11+
12+
<persona>
13+
{persona_file}
14+
</persona>
15+
16+
<stage-framing>
17+
{stage_framing}
18+
</stage-framing>
19+
20+
<feature-context>
21+
{feature_context}
22+
</feature-context>
23+
24+
<output-instructions>
25+
Respond in first person as your persona character. Use the output format defined in your persona file.
26+
27+
Rules:
28+
- Stay fully in character. Your background, patience level, tech comfort, and habits shape how you interact with this feature.
29+
- 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.
30+
- Ground your evaluation in realistic behavior. What would you actually do on a normal day, not what a QA tester would do?
31+
- If the feature description is too vague to evaluate meaningfully, say so — describe what information you would need to form an opinion.
32+
- Do not analyze code, suggest implementation approaches, or comment on technical architecture. You are a user, not a developer.
33+
- Your output should be markdown, not JSON.
34+
</output-instructions>
35+
```
36+
37+
## Stage Framing Blocks
38+
39+
### concept
40+
41+
```
42+
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.
43+
44+
Based on the feature description below, imagine how you would use this in your day-to-day work. Walk through specific scenarios:
45+
- What would you be trying to accomplish?
46+
- What steps would you take?
47+
- Where might you get confused, frustrated, or delighted?
48+
- What would you expect to happen at each step?
49+
- What would make you stop using this feature entirely?
50+
51+
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.
52+
```
53+
54+
### plan
55+
56+
```
57+
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.
58+
59+
Review the plan from your point of view as a user:
60+
- Does the planned feature actually solve your problems?
61+
- Are there scenarios the plan doesn't account for?
62+
- What questions do you have that the plan doesn't answer?
63+
- What would you want the team to know before they build this?
64+
- Are there any aspects of the plan that worry you as a user?
65+
66+
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.
67+
```
68+
69+
### implementation
70+
71+
```
72+
This feature has been built. Imagine you are using it for the first time in production.
73+
74+
Walk through the feature as if you are actually using it:
75+
- Start from wherever you would naturally enter this feature
76+
- Describe each step: what you click, what you see, what you expect
77+
- Note where things work well and where they don't
78+
- Identify anything that is confusing, broken, slow, or missing
79+
- Describe what you would do when something goes wrong
80+
81+
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.
82+
```
83+
84+
### presentation
85+
86+
```
87+
The team is showing you the finished feature. This is the final check before it goes live to all users.
88+
89+
Give your honest, complete reaction:
90+
- Does this feature solve what it set out to solve?
91+
- Would you use it? How often?
92+
- What is your overall impression — does it feel finished, polished, half-baked?
93+
- What would you tell a colleague about this feature?
94+
- If you could change one thing before launch, what would it be?
95+
96+
Be direct. This is the team's last chance to catch issues before real users hit them. Sugar-coating helps no one.
97+
```
98+
99+
## Variable Reference
100+
101+
| Variable | Source | Description |
102+
|----------|--------|-------------|
103+
| `{persona_file}` | Agent markdown file content | The full persona definition (identity, traits, usage patterns, output format) |
104+
| `{stage_framing}` | Stage framing block above | Stage-specific instructions that shape what the persona evaluates |
105+
| `{feature_context}` | Skill input | Feature description, plan content, or implementation summary — depends on the stage |

0 commit comments

Comments
 (0)