@ai-outfitter/outfitter 1.0.3 → 1.1.1

package/docs/documentation/usecases/persona-reviews.md

@@ -1,167 +1,118 @@
-# Persona Reviews
+# Persona reviews
 
-A persona review catalog gathers structured feedback on a product, docs, onboarding flow, or UX from the points of view of the people who might use it — before asking real prospects to spend time. It uses the [persona convention](../personas.md): **one base review agent** plus a **directory of persona description documents**, run once per document.
+A persona review gathers structured feedback on a product, docs, onboarding flow, or UX from the point of view of the people who might use it — before asking real prospects to spend time. It uses the [persona convention](../personas.md): **one shared review agent** plus **one committed Markdown file per persona**. The same file runs under Outfitter, and pastes unchanged into any web agent.
 
-There is no `personas:` map and no agent per customer type. The review rules live in a single agent; each persona is a cheap markdown file you feed it as input.
+## One persona, one file
 
-```text
-customer-review/                 # standalone .agents repo; root is the payload
-  agents/
-    reviewer/agent.md            # the base review agent
-  settings.yml
-docs/user-personas/
-  roles/                         # reusable job archetypes (shared segment priorities)
-    staff-engineer.md
-    founder-operator.md
-    platform-lead.md
-  individuals/                   # specific named people, each naming one or more roles
-    marcus-bell.md               # roles: [staff-engineer]
-    dana-okafor.md               # roles: [founder-operator]
-    priya-nair.md                # roles: [platform-lead]
-```
+The whole persona is one portable, self-contained Markdown document — a generic role archetype, H1 first, no frontmatter, first-person prose. Abridged from the canonical [`platform-lead.md`](https://github.com/ai-outfitter/community-profiles/blob/main/skills/persona-authoring/references/personas/platform-lead.md) reference:
 
-Personas come in two kinds of file, and a review **mixes and matches** them: a **role** carries the priorities everyone in a customer segment shares, and an **individual** is one named person who inherits one or more roles and adds their own demographics and voice. Keep roles reusable and individuals concrete, and you can cover a lot of viewpoints from a small set of files.
+```markdown
+# Platform Lead
 
-## Settings
+I'm the platform lead responsible for a consistent, reproducible agent setup
+across a mid-sized engineering organization.
 
-Settings only names the default agent and where resources resolve from — no persona list:
+## How I decide
 
-```yaml
-# settings.yml
-default_agent: reviewer
+I look for clear precedence, pinned sources, documented secret boundaries,
+least-privilege access, and tests showing that credentials stay isolated
+between layers. I check the escape hatch first.
 ```
 
-## The base review agent
-
-One agent holds the review method and the output shape. It does not name any customer type; it reads the persona files it is told to adopt, in order.
-
-```
-<!-- agents/reviewer/agent.md -->
----
-name: reviewer
-description: Reviews an artifact from the point of view of an assigned customer persona.
----
-
-Adopt the persona files named in your instructions, in order: a role file
-establishes the segment's priorities, and an individual file layers that
-person's demographics and voice on top (later files refine earlier ones). If
-an individual names roles in its frontmatter, treat those as its baseline.
-
-Read or experience the provided artifact from that persona's point of view:
-docs, screenshots, website, prototype, product flow, or onboarding path.
-Distinguish evidence from assumptions, cite the exact page or UI moment that
-shaped your reaction, and do not invent real customer research.
-
-Return feedback as: persona, artifact reviewed, first impression, top blocker,
-strongest value signal, confusing language, suggested change, and confidence.
-If you need more context, ask for the smallest missing artifact.
+The review method lives in the shared [`persona-reviewer`](https://github.com/ai-outfitter/community-profiles/blob/main/agents/persona-reviewer/agent.md) agent; each persona is a Markdown file you append to it.
+
+## Adopt persona reviews across an engineering organization
+
+A platform engineer installs Outfitter and uses the `platform` profile to
+configure a pinned [organization catalog](./organization-profile-catalog.md).
+The catalog reuses the default `engineer` profile, defines the organization's
+`marketing` profile, and makes the community persona-review components
+available to both. After setup and sync, engineers review products from the
+`engineer` profile while marketers review messaging from the `marketing`
+profile. Both profile loadouts select `persona-review`. When either role is
+asked to run a review, the skill launches the isolated shared reviewer with the
+selected customer persona and saves the report:
+
+```mermaid
+flowchart LR
+  subgraph platformTeam["Platform engineer — platform profile"]
+    install["Install Outfitter"] --> platform["outfitter run platform"]
+    platform --> catalog["Configure pinned org catalog"]
+  end
+
+  subgraph distribution["Organization distribution"]
+    catalog --> defaults["default-profiles<br/>engineer skills: persona-review"]
+    catalog --> marketing["Organization catalog<br/>marketing skills: persona-review"]
+    defaults --> community["community-profiles<br/>persona-review skill<br/>persona-reviewer agent"]
+  end
+
+  subgraph roleTeams["Engineering and marketing teams"]
+    setup["outfitter setup and sync"] --> engineer["outfitter run engineer"]
+    setup --> marketer["outfitter run marketing"]
+    engineer -->|"Product review"| skill["Use persona-review skill"]
+    marketer -->|"Messaging review"| skill
+    persona["Customer persona<br/>docs/personas/customer.md"] --> reviewer["Isolated persona-reviewer"]
+    artifact["Review target"] --> reviewer
+    skill --> reviewer
+    reviewer --> report["Durable customer-review report"]
+  end
+
+  catalog --> setup
+  community --> setup
+  marketing --> setup
 ```
 
-## Roles: reusable job archetypes
+The `platform`, `engineer`, and `marketing` profiles are executable roles. A
+customer persona supplies temporary identity context within the isolated
+reviewer process.
 
-A role captures what everyone in a customer segment shares — the job, its goals, anxieties, buying triggers, and what its feedback focuses on — with no personal detail. Roles are reused across many individuals.
+## Author it
 
-```
-<!-- docs/user-personas/roles/staff-engineer.md -->
----
-kind: role
-title: Staff Engineer
-segment: large-eng-org
-goals: [reduce cross-team friction, raise technical quality, adopt tools that survive scrutiny]
-anxieties: [tools that demo well but fail on a real codebase, unproven claims]
-buying_triggers: [credible examples, verifiable outcomes, a clean migration path]
-feedback_focus: [depth, verification paths, missing examples, evidence behind claims]
----
-
-Responsible for large codebases, architecture decisions, reviews, and
-cross-team technical quality. Cares whether the docs explain how the product
-improves real engineering work. Flags missing examples, weak verification
-paths, and claims that need evidence.
-```
+Start from the community catalog's [`template.persona.md`](https://github.com/ai-outfitter/community-profiles/blob/main/skills/persona-authoring/assets/template.persona.md) by hand, or let any agent that selects the [`persona-authoring`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-authoring) skill interview you into the file. Commit the result to normal project documentation:
 
-```
-<!-- docs/user-personas/roles/founder-operator.md -->
----
-kind: role
-title: Founder-operator
-segment: seed-stage-startup
-goals: [ship weekly, keep the team small, reach the next milestone before the runway ends]
-anxieties: [tool sprawl, hidden pricing, time lost to setup]
-buying_triggers: [obvious value in the first hour, no credit card to try]
-feedback_focus: [time-to-first-value, jargon, trust boundaries, pricing clarity]
----
-
-A hands-on founder who writes product specs, edits docs, ships small features,
-and manages a thin team. Cares whether the first hour feels obviously valuable.
+```text
+docs/personas/
+  platform-lead.md
+  founder-operator.md
 ```
 
-## Individuals: named people who inherit roles
+Prefer generic role archetypes over named individuals. Research and interviews are authoring inputs; commit only the self-contained file, and invent nothing the research does not support.
 
-An individual is one concrete person — with the demographics a [Lean Canvas](https://leanstack.com/lean-canvas) customer segment gets — who names one or more roles to inherit and then adds their own attributes and voice. The named person **mixes and matches** roles: usually one, but a founder who also runs the platform can list both.
+## Run it under Outfitter
 
-```
-<!-- docs/user-personas/individuals/marcus-bell.md -->
----
-kind: individual
-name: Marcus Bell
-roles: [staff-engineer]
-born: 1985-11-02
-location: Seattle, WA
-household_income: 265000
-education: MS Computer Engineering
-employer: ~400-engineer fintech
-hobbies: [rock climbing, sci-fi novels, restoring old synths]
-skills: [distributed systems, code review, architecture, mentoring]
-tone: dry, skeptical, cites sources
----
-
-Reads new tooling the way he reads a design doc: looking for the failure mode
-first. Warm once convinced, but will not take a benchmark on faith.
-```
+After `outfitter setup`, launch the shared reviewer directly with the persona appended and save its output:
 
-```
-<!-- docs/user-personas/individuals/dana-okafor.md -->
----
-kind: individual
-name: Dana Okafor
-roles: [founder-operator, platform-lead] # mixes two roles
-born: 1989-03-14
-location: Austin, TX
-household_income: 180000
-education: BS Computer Science
-employer: 6-person seed-stage startup (also the de facto platform owner)
-hobbies: [trail running, home espresso, mechanical keyboards]
-skills: [product specs, TypeScript, fundraising, hiring]
-tone: fast, pragmatic, allergic to jargon
----
-
-Wears the founder and the platform hat at once, so she weighs first-hour value
-against fleet-wide safety in the same breath. Impatient with setup friction.
+```sh
+mkdir -p docs/persona-reviews
+outfitter run persona-reviewer -- \
+  --append-system-prompt docs/personas/platform-lead.md \
+  --print "Review the onboarding flow and write the report. @README.md" \
+  > docs/persona-reviews/platform-lead-onboarding.md
 ```
 
-Keep the role attribute set consistent so reviews stay comparable, and let individuals vary freely in demographics and tone. Add more roles (`platform-lead`, `engineering-manager`, `agency-consultant`) and more individuals the same way.
+This is the portable interface: it works from the project containing the persona and does not assume a particular catalog checkout path. One shared agent adopts the file as its identity for that session only and writes a first-person, sourced report — evidence cited to the exact page or UI moment, assumptions labeled. The reviewer inherits the caller's configured model; reviews benefit from a strong reasoning model.
 
-## Running the reviews
+### Optional orchestration with the skill
 
-Run the base agent once per persona, naming the role and individual files to adopt and the artifact under review:
+Use the [`persona-review`](https://github.com/ai-outfitter/community-profiles/tree/main/skills/persona-review) skill when another agent should manage the review process. The skill owns synchronous or background execution and durable report capture. From a checkout of the community catalog, its repository-relative launcher is an optional convenience:
 
-```bash
-outfitter run reviewer -- --print \
-  "Adopt docs/user-personas/roles/staff-engineer.md refined by \
-   docs/user-personas/individuals/marcus-bell.md. Read README.md, \
-   docs/getting-started.md, and docs/pricing.md, then return the standard \
-   review shape: where the product feels credible, where it feels \
-   underspecified, and the one example that would most improve your confidence."
+```sh
+bash skills/persona-review/scripts/persona-review.sh \
+  --persona docs/personas/platform-lead.md \
+  --report docs/persona-reviews/platform-lead-onboarding.md \
+  -- --print "Review the onboarding flow and write the report. @README.md"
 ```
 
-```bash
-outfitter run reviewer -- --print \
-  "Adopt docs/user-personas/individuals/dana-okafor.md and the roles it names. \
-   Browse the local docs site and try the first-run setup flow. Report the \
-   first confusing moment, the first moment that felt valuable, and whether \
-   you would keep using it."
-```
+The reviewer runs directly as the selected agent. This journey does not require Pi's native subagent projection.
+
+## Take the same file to the web
+
+Paste or upload `docs/personas/platform-lead.md` unchanged into a claude.ai project's knowledge or a ChatGPT project and say: "Treat this as stakeholder context. Review the attached landing page from this persona's point of view." The file was written to read standalone, so a tool that takes Markdown project context can use it unchanged.
+
+## Why this shape
 
-Model and thinking choices — cheaper models for high-volume routing reviews, deeper reasoning for platform-risk reviews — live in the reviewer agent's loadout, or a machine-local override, rather than being duplicated per persona.
+- **One file per persona**: adding a persona adds a document, not another agent.
+- **Comparable reports**: one agent fixes the review method and output shape, so feedback from different persona files is directly comparable.
+- **No Outfitter dependency**: Outfitter is one optional consumer of a file that does not depend on it.
 
-Because the base agent fixes the output shape, feedback from every persona document is directly comparable. The result is a reusable customer-persona review catalog that reads docs or experiences a UX from many viewpoints without pretending to replace real customer discovery.
+See the [persona spec](../personas.md) for the format, and the community catalog's [persona boundary doc](https://github.com/ai-outfitter/community-profiles/blob/main/docs/persona-review.md) for the responsibility split between authoring, the shared reviewer, and project wrappers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-outfitter/outfitter",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "Profile-oriented wrapper for launching pi, Claude Code, and future agent CLIs with reproducible configuration.",
   "type": "module",
   "repository": {