@m8i-51/shoal 0.1.8 → 0.1.10

package/framework/org-designer.ts

@@ -4,7 +4,7 @@ import { createMessageWithRetry } from "./agent-loop";
 import type { ProductSpec } from "./product-discovery";
 
 export interface OrgDesign {
-  hrGuidance: string;
+  personaGuidance: string;
 }
 
 // Evaluation lenses always included regardless of app type / アプリ種別に関わらず常に含める観点
@@ -22,7 +22,7 @@ export const UNIVERSAL_LENSES = [
 ];
 
 export async function designOrg(spec: ProductSpec, client: LLMClient, model: string, coverageSummary?: string): Promise<OrgDesign> {
-  console.log("\n[org-design] starting...");
+  console.log("\n[persona-policy] starting...");
 
   const response = await createMessageWithRetry(client, {
     model,
@@ -47,18 +47,36 @@ ${spec.features}
 ${spec.designContext ? `\n[Design Context]\n${spec.designContext}\n` : ""}${coverageSummary ? `\n[Coverage History]\n${coverageSummary}\nUse this to identify underrepresented perspectives and adjust the recruitment policy accordingly.\n` : ""}
 Please output the following:
 
+## App type classification
+Classify this app as one of:
+- "business": used in work contexts by employees with specific job roles (CRM, project management, HR tools, etc.)
+- "consumer": used by individuals in personal contexts (personal finance, entertainment, health, productivity, etc.)
+- "mixed": significant use in both contexts
+
 ## User types for this app
-(What kinds of users exist — roles, skill levels, usage scenarios)
+(What kinds of users exist — described appropriately for the app type)
 
 ## Agent types to recruit (5–8 types)
-By job function, role, and technical literacy. Always include:
-- At least one UX/product designer persona (evaluates visual consistency, interaction patterns, HIG/Material compliance)
-- At least one product manager or business analyst persona (evaluates feature completeness, user journey clarity)
-- At least one target end-user with low technical literacy (first-time or reluctant user)
-- Domain-specific roles relevant to this app type
-
-## Recruitment instructions for the HR agent
-(Concrete hiring/retirement guidelines based on the above — emphasize persona diversity across technical skill levels, job functions, and design sensitivity)`,
+
+**If business app:**
+Recruit primarily by job role and function (e.g., sales rep, manager, admin).
+Include personas with varying technical literacy within those roles.
+
+**If consumer app:**
+Recruit primarily as real end-users — define by lifestyle, demographics, and usage context.
+Focus on who actually uses this app in daily life, not job titles.
+Examples for a subscription tracker: "budget-conscious student juggling streaming costs", "freelancer tracking SaaS tool expenses", "household manager reviewing family subscriptions".
+Avoid professional/specialist titles (QA engineer, PM, auditor) as primary personas — these are not real users of this app.
+
+**If mixed:**
+Balance job-role personas and lifestyle-based end-user personas.
+
+**Always include as supplement (1–2 personas regardless of app type):**
+- 1 UX evaluator: focuses on visual consistency, interaction patterns, HIG/Material compliance
+- 1 edge-case/accessibility evaluator: focuses on error handling, accessibility, stress scenarios
+
+## Recruitment instructions for the persona designer agent
+(Concrete guidelines based on the above — emphasize that the majority of personas should reflect real users of this specific app, with expert evaluators as a minority supplement)`,
       },
     ],
   });
@@ -68,7 +86,7 @@ By job function, role, and technical literacy. Always include:
     .map((b) => b.text)
     .join("");
 
-  const hrGuidance = `${text}
+  const personaGuidance = `${text}
 
 [Universal Evaluation Lenses]
 Include one of the following perspectives in each agent's persona to ensure diverse findings:
@@ -86,6 +104,6 @@ When recruiting UX/design-oriented agents, give them awareness of these standard
   - Jakob's Law: flag interactions that contradict conventions users expect from similar apps (e.g., swipe to delete, pull to refresh, hamburger menus)
   - Nielsen's heuristics: check for missing system status feedback, unclear error messages, lack of undo, and forcing users to recall rather than recognize`;
 
-  console.log("[org-design] done");
-  return { hrGuidance };
+  console.log("[persona-policy] done");
+  return { personaGuidance };
 }

package/framework/triage.ts

@@ -163,11 +163,12 @@ Organize feedback collected by multiple agents and post it as GitHub Issues.
           ? `\n\n**Screenshots:**\n${screenshots.join("\n")}`
           : "";
         const fullBody = `**Category:** ${category}\n\n${body}${screenshotSection}\n\n---\n**Reported by:** ${mergedAgents.join(", ")}\n*This Issue was auto-generated by an AI triage agent*`;
-        const url = await postGitHubIssue(`[${category}] ${title}`, fullBody, [category, "feedback-agent"], githubOptions);
+        const cleanTitle = title.replace(/^\[[^\]]+\]\s*/i, "");
+        const url = await postGitHubIssue(`[${category}] ${cleanTitle}`, fullBody, [category, "feedback-agent"], githubOptions);
         mergedIds.forEach((id) => { pendingIds.delete(id); issuedIds.push(id); });
         issuesCreated++;
         result = { created: true, url, mergedCount: mergedIds.length };
-        console.log(`  [triage] issue created: "${title}" (merged ${mergedIds.length})`);
+        console.log(`  [triage] issue created: "[${category}] ${cleanTitle}" (merged ${mergedIds.length})`);
 
       } else if (toolUse.name === "skip_finding") {
         const { finding_id, reason } = toolUse.input as { finding_id: string; reason: string };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
   "repository": {

package/run.ts

@@ -394,10 +394,10 @@ ${productSpec.uiFeatures ? `\n[UI-Only Features]\nThese features exist in the UI
 }
 
 // ================================================================
-// HR agent
+// Persona designer agent
 // ================================================================
 
-const HR_TOOLS: Anthropic.Tool[] = [
+const PERSONA_DESIGNER_TOOLS: Anthropic.Tool[] = [
   {
     name: "get_agents",
     description: "Get the current list of registered agents. / 現在登録されているエージェント一覧を取得する",
@@ -445,24 +445,24 @@ const HR_TOOLS: Anthropic.Tool[] = [
   },
 ];
 
-async function runHRAgent(
+async function runPersonaDesigner(
   productSpec: ProductSpec,
   orgGuidance: string,
   openIssues: { number: number; title: string; labels: string[] }[],
   scenarios: Scenario[],
   testAccounts: TestAccount[] = [],
 ): Promise<void> {
-  console.log("\n[hr] starting...");
+  console.log("\n[persona-designer] starting...");
   const messages: Anthropic.MessageParam[] = [
-    { role: "user", content: "Manage agent hiring and retirement." },
+    { role: "user", content: "Design and manage user personas for this run." },
   ];
 
   const accountContext = testAccounts.length > 0
     ? `\n[Available Test Accounts (one per role)]\n${testAccounts.map((a) => `- ${a.role}: ${a.email}`).join("\n")}\nWhen recruiting agents, match each persona's role to one of these accounts so they can operate with appropriate permissions.`
     : "";
 
-  const systemPrompt = `You are the test agent manager for "${productSpec.appName}".
-You recruit and manage agents that simulate real users of the app.
+  const systemPrompt = `You are the persona designer for "${productSpec.appName}".
+You create and manage test agents that simulate real users of the app.
 
 [Organization Design Guidelines]
 ${orgGuidance}${accountContext}
@@ -483,7 +483,7 @@ ${orgGuidance}${accountContext}
         model: defaultModel,
         max_tokens: 1024,
         system: systemPrompt,
-        tools: HR_TOOLS,
+        tools: PERSONA_DESIGNER_TOOLS,
         messages,
       });
       messages.push({ role: "assistant", content: response.content });
@@ -496,14 +496,14 @@ ${orgGuidance}${accountContext}
         let result: unknown;
         if (toolUse.name === "get_coverage") {
           result = computeWeightedSummary().formatted;
-          console.log("  [hr] coverage summary fetched");
+          console.log("  [persona-designer] coverage summary fetched");
         } else if (toolUse.name === "get_open_issues") {
           if (openIssues.length === 0) {
             result = "(no open issues — either GitHub is not configured or there are no known issues yet)";
           } else {
             result = openIssues.map((i) => `- #${i.number}: ${i.title} [${i.labels.join(", ")}]`).join("\n");
           }
-          console.log(`  [hr] open issues fetched (${openIssues.length})`);
+          console.log(`  [persona-designer] open issues fetched (${openIssues.length})`);
         } else if (toolUse.name === "get_scenarios") {
           if (scenarios.length === 0) {
             result = "(no scenarios generated — all agents will use free-exploration mode)";
@@ -512,19 +512,19 @@ ${orgGuidance}${accountContext}
               `[${s.id}] ${s.title}\n  Context: ${s.context}\n  Goal: ${s.goal}\n  Constraints: ${s.constraints}`
             ).join("\n\n");
           }
-          console.log(`  [hr] scenarios fetched (${scenarios.length})`);
+          console.log(`  [persona-designer] scenarios fetched (${scenarios.length})`);
         } else if (toolUse.name === "get_agents") {
           const agents = loadAgents();
           result = agents.map((a) => ({ id: a.id, name: a.name, role: a.role, createdAt: a.createdAt }));
-          console.log(`  [hr] current agents: ${agents.length}`);
+          console.log(`  [persona-designer] current agents: ${agents.length}`);
         } else if (toolUse.name === "add_agent") {
           const { name, role, persona } = toolUse.input as { name: string; role: string; persona: string };
           result = addAgent({ name, role, persona });
-          console.log(`  [hr] hired: ${name} (${role})`);
+          console.log(`  [persona-designer] created: ${name} (${role})`);
         } else if (toolUse.name === "retire_agent") {
           const { agentId, reason } = toolUse.input as { agentId: string; reason: string };
           result = { success: retireAgent(agentId) };
-          console.log(`  [hr] retired: ${agentId} — ${reason}`);
+          console.log(`  [persona-designer] retired: ${agentId} — ${reason}`);
         } else {
           result = { error: "unknown tool" };
         }
@@ -532,9 +532,9 @@ ${orgGuidance}${accountContext}
       }
       messages.push({ role: "user", content: toolResults });
     }
-    console.log("[hr] done");
+    console.log("[persona-designer] done");
   } catch (e) {
-    console.error("[hr] error:", e);
+    console.error("[persona-designer] error:", e);
   }
 }
 
@@ -691,7 +691,7 @@ async function executeBrowserTool(
         const { path: navPath } = input as { path: string };
         await saveSnapshotBeforeAction(page, observation);
         await page.goto(`${BASE_URL}${navPath}`, { waitUntil: "networkidle" });
-        await page.waitForTimeout(500);
+        await page.waitForTimeout(3000);
         screenshot = await takeScreenshot(page, `navigate_${navPath.replace(/\//g, "_")}`);
         resultText = `Navigated to ${navPath}`;
         break;
@@ -925,7 +925,7 @@ ${productSpec.designContext ? `\n[Design Context]\n${productSpec.designContext}\
     : ""}`;
 
   await page.goto(BASE_URL, { waitUntil: "networkidle" });
-  await page.waitForTimeout(1000);
+  await page.waitForTimeout(5000);
   const initialScreenshot = await takeScreenshot(page, "initial");
 
   const messages: Anthropic.MessageParam[] = [
@@ -1105,7 +1105,7 @@ async function main() {
     }
 
     // 4. HR agent
-    await runHRAgent(productSpec, orgDesign.hrGuidance, openIssues, scenarios, testAccounts);
+    await runPersonaDesigner(productSpec, orgDesign.personaGuidance, openIssues, scenarios, testAccounts);
 
     // 5. load agents + closed issues
     const allAgents = loadAgents();