@shahmarasy/prodo 0.1.3 → 0.1.5

package/presets/marketplace/prompts/prd.md

@@ -1,3 +1,141 @@
-Preset: marketplace
+# Marketplace Preset - PRD Generation Context
 
-Use domain-specific terminology and constraints for marketplace products.
+## Preset Overview
+**Domain**: Multi-Sided Marketplace
+**Focus**: Trust & safety, multi-stakeholder coordination, sustainable growth, community health
+**Target Models**: B2C, C2C, Gig Economy, Subscription, SaaS Marketplaces
+
+## Critical Requirements for Marketplace Products
+
+### 1. Multi-Stakeholder Coordination
+- **Buyers**: Search, discovery, purchasing, reviews, ratings
+- **Sellers**: Listing creation, inventory management, order fulfillment
+- **Platform**: Commission structure, dispute resolution, policy enforcement
+- **Moderators**: Content review, policy compliance, community health
+- **Support**: Buyer/seller support, dispute handling, escalations
+
+### 2. Trust & Safety Mechanisms
+- **Identity Verification**: Seller verification, buyer profiles, trust scoring
+- **Review System**: Authentic reviews, review moderation, rating accuracy
+- **Dispute Resolution**: Clear process, fair arbitration, appeal mechanisms
+- **Fraud Prevention**: Transaction monitoring, chargeback protection, seller vetting
+- **Community Standards**: Content policies, community guidelines, enforcement
+
+### 3. Commission & Payment Systems
+- **Revenue Model**: Commission % for platform sustainability
+- **Payment Processing**: Buyer payments, seller payouts, tax handling
+- **Pricing Strategy**: Dynamic pricing, surge pricing, discounts
+- **Seller Incentives**: Top performer rewards, quality bonuses
+- **Payout Timing**: Immediate, delayed, or tiered payout options
+
+### 4. Seller Quality Assurance
+- **Onboarding**: Seller verification, document collection, quality baseline
+- **Performance Metrics**: Response rate, cancellation rate, rating average
+- **Quality Enforcement**: Warnings, suspensions, bans for policy violations
+- **Support**: Seller success resources, training, API documentation
+- **Tiering**: Seller levels (new, standard, gold, platinum) with benefits
+
+### 5. Discovery & Matching
+- **Search**: Full-text search, filters, sorting
+- **Recommendations**: ML-based recommendations, personalization
+- **Trending**: What's hot, seasonal items, category trending
+- **Supply/Demand**: Balancing supply scarcity with buyer demand
+- **Ranking Algorithm**: Fair ranking, preventing gaming, transparency
+
+### 6. Community Moderation
+- **Content Review**: Image verification, description moderation
+- **Review Management**: Review authenticity, spam detection, manipulation prevention
+- **User Behavior**: Community standards, suspension/ban procedures
+- **Appeal Process**: Fair appeals, transparency, communication
+- **Transparency**: Clear policies, community guidelines, moderation appeals
+
+### 7. User Personas (Marketplace Specific)
+
+#### Buyer Persona
+- Goals: Find best products, competitive prices, fast delivery
+- Pain Points: Counterfeit items, long delivery, poor service
+- Concerns: Trust in seller, payment security, return policies
+
+#### Seller Persona
+- Goals: Reach customers, maximize revenue, sustainable growth
+- Pain Points: Finding customers, competition, payment processing
+- Concerns: Commission rates, policy changes, fair treatment
+
+#### Platform Operator
+- Goals: Sustainable growth, healthy marketplace, stakeholder satisfaction
+- Pain Points: Balancing buyer/seller interests, fraud, legal compliance
+- Concerns: GMV growth, trust metrics, user satisfaction
+
+#### Support Agent
+- Goals: Resolve disputes fairly, maintain trust, reduce escalations
+- Pain Points: Complex disputes, policy ambiguity, seller/buyer conflicts
+- Concerns: Fair resolution, quick closure, customer satisfaction
+
+#### Community Moderator
+- Goals: Maintain community standards, prevent abuse, engage users
+- Pain Points: Volume of content, policy interpretation, false positives
+- Concerns: Bias, false negatives, user resentment
+
+### 8. Success Metrics (Marketplace Specific)
+- **Gross Merchandise Volume (GMV)**: Total transaction value
+- **Seller Growth**: New sellers, active sellers, seller satisfaction
+- **Customer Retention**: Repeat purchase rate, churn rate
+- **Review Authenticity**: % of authentic reviews (fraud detection rate)
+- **Dispute Rate**: Disputes as % of transactions (lower is better)
+- **Trust Score**: Buyer trust in platform, Net Promoter Score (NPS)
+- **Seller Health**: Average seller rating, suspension rate, appeal rate
+- **Community Health**: Content removal rate, user suspension rate, community satisfaction
+
+### 9. Key Constraints
+- **Commission Structure**: Sustainable for platform, fair to sellers
+- **Payout Timing**: Fast enough for seller satisfaction, safe for platform
+- **Dispute Deadlines**: Quick resolution, legal time requirements
+- **Content Policies**: Clear standards, consistent enforcement
+- **Data Privacy**: PII protection, transaction privacy, seller anonymity options
+- **Regulatory**: Tax collection, consumer protection, local regulations
+
+## PRD Generation Guidelines
+
+### Multi-Stakeholder Perspective
+Always consider impact on:
+- ✅ Buyers: Is this feature valuable and trustworthy?
+- ✅ Sellers: Is this feature fair and sustainable?
+- ✅ Platform: Does this drive growth and profitability?
+- ✅ Community: Does this maintain or improve community health?
+
+### Trust-First Approach
+- Every feature must enhance or maintain trust
+- Transparency over features
+- Fair treatment over growth hacks
+- Community health over short-term metrics
+
+### Commission & Pricing
+- Make commission % explicit in documentation
+- Justify pricing to both buyers and sellers
+- Show how platform uses commissions
+- Consider seller profitability models
+
+### Dispute Resolution
+- Clear escalation paths
+- Fair arbitration criteria
+- Appeal mechanisms
+- Transparent timeline
+
+### Seller Success
+- Onboarding clear and supportive
+- Performance metrics transparent
+- Success resources available
+- Fair quality enforcement
+
+## Validation Checklist
+Before finalizing PRD, verify:
+- ✅ All stakeholders considered (buyer, seller, platform, moderator, support)
+- ✅ Trust mechanisms clearly defined
+- ✅ Commission structure documented
+- ✅ Dispute resolution process outlined
+- ✅ Seller quality criteria explicit
+- ✅ Community guidelines clear
+- ✅ Payment flow documented (buyer → platform → seller)
+- ✅ Moderation policies defined
+- ✅ Fairness across stakeholders assessed
+- ✅ Scalability for growth considered

package/presets/saas/preset.json

@@ -1 +1,53 @@
-{"name":"saas","priority":1,"min_prodo_version":"0.1.0","version":"1.0.0"}
+{
+  "name": "saas",
+  "display_name": "Software as a Service (SaaS)",
+  "description": "Comprehensive preset for SaaS products with subscription models, enterprise integration, scalability, customer success focus, and API-first architecture",
+  "category": "domain-specific",
+  "priority": 1,
+  "min_prodo_version": "0.1.0",
+  "version": "1.0.0",
+  "metadata": {
+    "domain": "Software as a Service",
+    "industry_focus": ["Enterprise Software", "Business Tools", "Workflow Automation", "Analytics", "Vertical SaaS"],
+    "business_model": ["subscription", "per-seat", "usage-based", "hybrid"],
+    "deployment_model": ["multi-tenant", "single-tenant", "hybrid"],
+    "key_complexity": "enterprise scale, integration requirements, customer success"
+  },
+  "preset_features": {
+    "domain_expertise": [
+      "Subscription billing & recurring revenue",
+      "Enterprise integration (SSO, SAML, APIs)",
+      "Customer success & retention strategies",
+      "Scalability & multi-tenancy",
+      "API design & developer experience",
+      "Compliance & data governance (SOC 2, HIPAA, GDPR)",
+      "Usage analytics & metering",
+      "Self-serve onboarding & product-led growth"
+    ],
+    "templates_included": ["prd"],
+    "context_enrichment": {
+      "user_personas": ["End User", "Admin/IT", "Finance Lead", "Customer Success Manager", "Developer"],
+      "success_metrics": ["Monthly Recurring Revenue (MRR)", "Customer Acquisition Cost (CAC)", "Lifetime Value (LTV)", "Churn rate", "NPS"],
+      "constraints": ["Uptime SLA", "Integration requirements", "Compliance standards", "Data residency", "Support tiers"]
+    }
+  },
+  "agent_requirements": {
+    "required_expertise": [
+      "SaaS business model understanding",
+      "Enterprise customer needs",
+      "Subscription economics",
+      "Integration architecture",
+      "Customer success strategies",
+      "Scalability planning"
+    ],
+    "recommended_agents": ["SaaS PM", "Enterprise Architect", "Customer Success Lead", "DevOps/Infrastructure Lead"],
+    "critical_validation": ["Pricing model", "Uptime SLA", "Integration roadmap", "Churn prevention strategy"]
+  },
+  "prompt_configuration": {
+    "tone": "Professional, enterprise-focused, customer-success-oriented",
+    "pricing_strategy": "transparent-value-based",
+    "customer_journey": "onboarding → adoption → expansion → retention",
+    "integration_first": "API-first, extensibility-critical",
+    "documentation_level": "comprehensive (API docs, admin guides, playbooks)"
+  }
+}

package/presets/saas/prompts/prd.md

@@ -1,3 +1,151 @@
-Preset: saas
+# SaaS Preset - PRD Generation Context
 
-Use domain-specific terminology and constraints for saas products.
+## Preset Overview
+**Domain**: Software as a Service (SaaS)
+**Focus**: Subscription economics, customer success, enterprise integration, scalability, recurring revenue
+**Target Models**: Enterprise Software, Business Tools, Vertical SaaS, Workflow Automation, Analytics
+
+## Critical Requirements for SaaS Products
+
+### 1. Subscription Business Model
+- **Pricing Tiers**: Free/Freemium, Starter, Professional, Enterprise
+- **Billing Cycle**: Monthly, annual, or usage-based
+- **Per-Seat vs. Fixed**: User-based vs. flat-rate pricing
+- **Feature Gating**: Which features per tier
+- **Contract Terms**: Auto-renewal, cancellation terms, trial periods
+
+### 2. Customer Onboarding & Adoption
+- **Self-Serve Onboarding**: Guided setup, templates, presets
+- **Product-Led Growth**: Feature discoverability, in-app education
+- **User Training**: Tutorials, help center, webinars, documentation
+- **Activation**: Time to first value, key engagement metrics
+- **Expansion Path**: Upsell opportunities, feature education
+
+### 3. Enterprise Integration
+- **SSO/SAML**: Single sign-on for corporate users
+- **APIs**: REST/GraphQL APIs for custom integrations
+- **Webhooks**: Real-time event notifications
+- **Data Export**: Export capabilities, compliance
+- **Native Integrations**: Slack, Salesforce, HubSpot, Jira, etc.
+
+### 4. Scalability & Multi-Tenancy
+- **Tenant Isolation**: Data separation and security
+- **Performance**: Sub-second response times
+- **Availability**: 99.9% or 99.99% uptime SLA
+- **Disaster Recovery**: Backup, replication, failover
+- **Geographic Distribution**: Multi-region support
+
+### 5. Customer Success & Retention
+- **Onboarding Support**: Dedicated CSM for enterprise accounts
+- **Health Scoring**: Identify at-risk customers proactively
+- **Usage Analytics**: Monitor feature adoption and user behavior
+- **Support Tiers**: Community, email, chat, phone, 24/7
+- **Renewal Playbook**: Steps to improve retention
+
+### 6. Compliance & Data Governance
+- **SOC 2**: Security, availability, confidentiality standards
+- **HIPAA**: For healthcare SaaS
+- **GDPR/CCPA**: Data privacy and right to deletion
+- **Data Residency**: Geographic data storage requirements
+- **Audit Trails**: Logging for compliance audits
+
+### 7. User Personas (SaaS Specific)
+
+#### End User
+- Goals: Solve their job efficiently, learn easily
+- Pain Points: Complex workflows, context-switching, training
+- Concerns: Time investment, productivity gain
+
+#### Admin/IT
+- Goals: Secure deployment, central management, compliance
+- Pain Points: User management overhead, security config
+- Concerns: Data security, compliance, integration complexity
+
+#### Finance Lead
+- Goals: ROI justification, cost optimization, budgeting
+- Pain Points: License management, usage visibility
+- Concerns: TCO, renewal negotiations, cost per user
+
+#### Customer Success Manager
+- Goals: Customer adoption, expansion, retention
+- Pain Points: Health scoring accuracy, expansion opportunities
+- Concerns: Churn prevention, engagement metrics, renewal success
+
+#### Developer (if applicable)
+- Goals: Easy integration, extensibility, good documentation
+- Pain Points: API limitations, rate limits, debugging
+- Concerns: Developer experience, SDK quality, support
+
+### 8. Success Metrics (SaaS Specific)
+- **Monthly Recurring Revenue (MRR)**: Predictable revenue base
+- **Annual Recurring Revenue (ARR)**: Annualized MRR
+- **Customer Acquisition Cost (CAC)**: Cost to acquire customer
+- **Lifetime Value (LTV)**: Total revenue per customer
+- **LTV:CAC Ratio**: Should be 3:1 or higher (industry standard)
+- **Churn Rate**: Monthly % of customers leaving
+- **Net Revenue Retention (NRR)**: Retention + expansion
+- **Customer Health Score**: Predictive churn indicator
+- **Net Promoter Score (NPS)**: Customer satisfaction
+- **Time to Value (TTV)**: Days to first value realization
+
+### 9. Key Constraints
+- **Uptime SLA**: 99.9% minimum (often 99.99% expected)
+- **Data Residency**: Specific geographic regions required
+- **Integration Requirements**: Must support popular tools
+- **Pricing Sensitivity**: Competitive pricing pressure
+- **Contract Terms**: Annual vs. monthly, lock-in periods
+- **Support Costs**: Scale with customer base and tier
+- **Regulatory Requirements**: Compliance obligations
+
+## PRD Generation Guidelines
+
+### Subscription-First Thinking
+- Every feature → How does it impact retention?
+- Every feature → Expansion opportunity or anti-churn?
+- Every feature → Which tier includes it?
+- Pricing change → Impact on LTV and churn?
+
+### Customer Success Playbook
+- How do we onboard customers?
+- How do we measure adoption?
+- How do we identify expansion opportunities?
+- How do we prevent churn?
+- What's the health scoring model?
+
+### Enterprise Requirements
+- What integrations are table-stakes?
+- What compliance is required?
+- What's the uptime SLA?
+- What's the support model?
+- What's the pricing model for enterprise?
+
+### API-First Design
+- What's exposed via API?
+- What data can be exported?
+- What webhooks/events exist?
+- Rate limiting strategy?
+- Documentation quality?
+
+### Scalability Considerations
+- How does the system scale to 10k users?
+- How does the system scale to 100k users?
+- What's the performance baseline?
+- What monitoring is needed?
+- What's the disaster recovery plan?
+
+## Validation Checklist
+Before finalizing PRD, verify:
+- ✅ Pricing model clearly defined (tiers, billing, trial)
+- ✅ Onboarding flow documented (self-serve path)
+- ✅ Key integrations listed
+- ✅ SLA/uptime committed (99.9% minimum)
+- ✅ Compliance requirements identified
+- ✅ Customer success strategy outlined
+- ✅ Health scoring model conceptualized
+- ✅ Support tier structure defined
+- ✅ Churn prevention strategy exists
+- ✅ Expansion/upsell opportunities identified
+- ✅ API strategy documented
+- ✅ Multi-tenancy approach clear
+- ✅ Disaster recovery plan outlined
+- ✅ Geographic expansion strategy noted

package/src/agents/agent-registry.ts

@@ -0,0 +1,93 @@
+import type { AgentPlugin } from "./base";
+import { UserError } from "../core/errors";
+import type { LLMProvider } from "../core/types";
+import { MockAgent } from "./mock";
+import { OpenAIAgent } from "./openai";
+import { AnthropicAgent } from "./anthropic";
+import { GoogleAgent } from "./google";
+
+const AGENT_ALIASES: Record<string, string> = {
+  mock: "mock",
+  openai: "openai",
+  anthropic: "anthropic",
+  claude: "anthropic",
+  google: "google",
+  gemini: "google"
+};
+
+export class AgentRegistry {
+  private agents = new Map<string, AgentPlugin>();
+
+  register(agent: AgentPlugin): void {
+    this.agents.set(agent.name, agent);
+  }
+
+  list(): AgentPlugin[] {
+    return Array.from(this.agents.values());
+  }
+
+  get(name: string): AgentPlugin | undefined {
+    const normalized = AGENT_ALIASES[name.toLowerCase().trim()] ?? name.toLowerCase().trim();
+    return this.agents.get(normalized);
+  }
+
+  async resolve(name?: string): Promise<AgentPlugin> {
+    const agentName = this.resolveAgentName(name);
+    const agent = this.get(agentName);
+
+    if (!agent) {
+      const available = this.list().map((a) => a.name).join(", ");
+      throw new UserError(
+        `Unknown agent: "${agentName}". Available agents: ${available}`
+      );
+    }
+
+    return agent;
+  }
+
+  private resolveAgentName(override?: string): string {
+    if (override) return override;
+
+    const fromEnv = process.env.PRODO_AGENT;
+    if (fromEnv) return fromEnv;
+
+    const fromLegacy = process.env.PRODO_LLM_PROVIDER;
+    if (fromLegacy) return fromLegacy;
+
+    const isTest =
+      process.env.NODE_ENV === "test" ||
+      process.env.PRODO_TEST === "1";
+    if (isTest) return "mock";
+
+    return "mock";
+  }
+
+  toProvider(agent: AgentPlugin): LLMProvider {
+    return {
+      generate: (prompt, inputContext, schemaHint) =>
+        agent.generate(prompt, inputContext, schemaHint)
+    };
+  }
+}
+
+let globalRegistry: AgentRegistry | null = null;
+
+function createDefaultRegistry(): AgentRegistry {
+  const registry = new AgentRegistry();
+  registry.register(new MockAgent());
+  registry.register(new OpenAIAgent());
+  registry.register(new AnthropicAgent());
+  registry.register(new GoogleAgent());
+  return registry;
+}
+
+export function getGlobalRegistry(): AgentRegistry {
+  if (!globalRegistry) {
+    globalRegistry = createDefaultRegistry();
+  }
+  return globalRegistry;
+}
+
+export function resetGlobalRegistry(): void {
+  globalRegistry = null;
+}

package/src/agents/anthropic/index.ts

@@ -0,0 +1,86 @@
+import { BaseAgent, type AgentConfig } from "../base";
+import { buildSystemPrompt, buildUserMessage } from "../system-prompts";
+import { UserError } from "../../core/errors";
+import type { GenerateResult, ProviderSchemaHint } from "../../core/types";
+
+const dynamicImport = new Function("specifier", "return import(specifier)") as (
+  specifier: string
+) => Promise<unknown>;
+
+type ContentBlock = { type: string; text?: string };
+
+export class AnthropicAgent extends BaseAgent {
+  readonly name = "anthropic";
+  readonly displayName = "Anthropic Claude";
+  readonly sdkRequired = "@anthropic-ai/sdk";
+
+  getConfig(): AgentConfig {
+    return {
+      name: this.name,
+      displayName: this.displayName,
+      sdkRequired: this.sdkRequired,
+      envVars: ["ANTHROPIC_API_KEY"],
+      defaultModel: "claude-sonnet-4-20250514"
+    };
+  }
+
+  async generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult> {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+      throw new UserError("ANTHROPIC_API_KEY is not set. Set it to use the Anthropic agent.");
+    }
+
+    const model = process.env.PRODO_ANTHROPIC_MODEL ?? "claude-sonnet-4-20250514";
+
+    const outputLanguage =
+      typeof inputContext.outputLanguage === "string" && inputContext.outputLanguage.trim()
+        ? inputContext.outputLanguage.trim()
+        : "en";
+
+    const system = buildSystemPrompt(schemaHint, outputLanguage);
+    const user = buildUserMessage(prompt, inputContext);
+
+    let AnthropicConstructor: new (opts: { apiKey: string }) => {
+      messages: {
+        create: (params: Record<string, unknown>) => Promise<{
+          content: ContentBlock[];
+        }>;
+      };
+    };
+
+    try {
+      const mod = (await dynamicImport("@anthropic-ai/sdk")) as {
+        default: typeof AnthropicConstructor;
+      };
+      AnthropicConstructor = mod.default;
+    } catch {
+      throw new UserError(
+        "Anthropic SDK is not installed. Run: npm install @anthropic-ai/sdk"
+      );
+    }
+
+    const client = new AnthropicConstructor({ apiKey });
+
+    const response = await client.messages.create({
+      model,
+      max_tokens: 8192,
+      system,
+      messages: [{ role: "user", content: user }]
+    });
+
+    const textBlock = response.content.find(
+      (block: ContentBlock) => block.type === "text"
+    );
+    const content = textBlock?.text?.trim() ?? "";
+
+    if (!content) {
+      throw new UserError("Anthropic agent returned an empty response.");
+    }
+
+    return { body: content };
+  }
+}

package/src/agents/anthropic/manifest.json

@@ -0,0 +1,7 @@
+{
+  "name": "anthropic",
+  "displayName": "Anthropic Claude",
+  "sdkRequired": "@anthropic-ai/sdk",
+  "envVars": ["ANTHROPIC_API_KEY"],
+  "defaultModel": "claude-sonnet-4-20250514"
+}

package/src/agents/base.ts

@@ -0,0 +1,77 @@
+import type { GenerateResult, ProviderSchemaHint } from "../core/types";
+
+export type AgentConfig = {
+  name: string;
+  displayName: string;
+  sdkRequired: string | null;
+  envVars: string[];
+  defaultModel?: string;
+};
+
+export interface AgentPlugin {
+  readonly name: string;
+  readonly displayName: string;
+  readonly sdkRequired: string | null;
+
+  generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult>;
+
+  isAvailable(): Promise<boolean>;
+  getConfig(): AgentConfig;
+}
+
+export abstract class BaseAgent implements AgentPlugin {
+  abstract readonly name: string;
+  abstract readonly displayName: string;
+  abstract readonly sdkRequired: string | null;
+
+  abstract generate(
+    prompt: string,
+    inputContext: Record<string, unknown>,
+    schemaHint: ProviderSchemaHint
+  ): Promise<GenerateResult>;
+
+  abstract getConfig(): AgentConfig;
+
+  async isAvailable(): Promise<boolean> {
+    const config = this.getConfig();
+
+    if (config.sdkRequired) {
+      try {
+        await import(config.sdkRequired);
+      } catch {
+        return false;
+      }
+    }
+
+    for (const envVar of config.envVars) {
+      if (!process.env[envVar]) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  availabilityHint(): string {
+    const config = this.getConfig();
+    const hints: string[] = [];
+
+    if (config.sdkRequired) {
+      hints.push(`SDK required: npm install ${config.sdkRequired}`);
+    }
+
+    for (const envVar of config.envVars) {
+      if (!process.env[envVar]) {
+        hints.push(`Set environment variable: ${envVar}`);
+      }
+    }
+
+    return hints.length > 0
+      ? `Agent "${config.displayName}" is not available.\n  ${hints.join("\n  ")}`
+      : `Agent "${config.displayName}" is available.`;
+  }
+}