# maxkmet/idea-validation-agents architecture

> Architecture diagram of the GitHub repository maxkmet/idea-validation-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxkmet/idea-validation-agents
- Repository: https://github.com/maxkmet/idea-validation-agents

## Overview

1. This repository is not a traditional app or service; it is a multi-platform AI agent playbook. The “runtime” is the user’s chat in Claude Code, OpenAI Codex CLI, or Cursor, which reads the repo’s instruction files and routes the conversation into the right validation workflow.

2. There are three platform-specific integration layers:
   - `CLAUDE.md` for Claude Code
   - `AGENTS.md` for Codex
   - `.cursor/rules/` for Cursor  
   These act as entry-point adapters that tell each tool how to behave and which workflow to activate.

3. The core capability is packaged as modular skills. The main skill set lives under `skills/`, with mirrored copies under `.claude/skills/` and `.codex/skills/` for platform compatibility. The skills are narrowly scoped analysis modules such as:
   - trend analysis
   - competitor mapping
   - desire evaluation
   - pricing and willingness-to-pay
   - distribution analysis
   - retention prediction
   - CAC modeling
   - TAM/SAM/SOM estimation
   - pivoting
   - decision memo generation

4. Workflow orchestration is defined separately from the skills. The `workflows/` folder contains the user-facing pipelines:
   - `idea-generation.md`
   - `idea-validation.md`
   - `market-deep-dive.md`
   - `pivot-optimization.md`  
   These workflows chain multiple skills together in a fixed sequence, so the architecture is “workflow-first” rather than “single-agent prompt”.

5. The main data flow starts with a user prompt, then branches into one of the workflows, which in turn invokes the relevant skills. For example, validation flows through trend research, competition analysis, pricing, distribution, retention, CAC, then a final score and decision memo. Idea generation starts with a founder/background interview before trend mining and scoring.

6. External research sources materially shape the analysis layer. The README names the main market inputs as TikTok Creative Center, Reddit, X/Twitter, App Store, and Google Trends. These are not just references; they are the evidence sources used to infer demand signals, competitor gaps, and distribution opportunities.

7. State is persisted on disk, not in a database. The `memory/` directory is the repository’s long-lived storage boundary and keeps results between sessions. It contains:
   - `user_profile.md` for reusable founder context
   - `memory/ideas/` for per-idea artifacts
   - `memory/market_insights/` for category research outputs
   - extra context files like `memory/extra-context/core-human-desires.md`  
   This makes the system session-independent and lets later workflows reuse prior analysis.

8. The outputs are artifact-driven and human-readable. Different workflows write different deliverables, including:
   - scored idea lists
   - competitor and pricing JSON
   - market insight markdown files
   - `decision_memo.md`
   - `pivot_options.json`  
   The repository is optimized for generating structured analysis packages rather than executable code.

9. The repository also has a documentation duplication boundary. `skills/`, `.claude/skills/`, `.codex/skills/`, and `.cursor/rules/` contain similar conceptual content but in the format each platform expects. That suggests the architecture’s portability strategy is “same knowledge, multiple tool-specific wrappers.”

10. Overall, the system architecture is:
   user chat → platform adapter (`CLAUDE.md` / `AGENTS.md` / Cursor rules) → workflow orchestration → modular skills → external market signals + local memory → saved decision artifacts.  
   For an architecture diagram, the important boundaries are the chat surface, the workflow engine, the reusable skill library, the external research sources, and the filesystem-backed memory layer.

Main entry points: [`workflows/idea-validation.md`](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/idea-validation.md) (Idea validate), [`skills/trend-analysis/SKILL.md`](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/trend-analysis/SKILL.md) (Trend analysis), [`memory`](https://github.com/maxkmet/idea-validation-agents/tree/main/memory) (Memory), [`workflows/README.md`](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/README.md) (Workflow guide)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_adapters["Platform Adapters"]
  node_claude_md["CLAUDE.md<br/>adapter<br/>[CLAUDE.md]"]
  node_agents_md["AGENTS.md<br/>adapter<br/>[AGENTS.md]"]
  node_cursor_rules["Cursor rules<br/>adapter<br/>[rules]"]
end

subgraph group_group_workflows["Workflows"]
  node_workflows_readme["Workflow guide<br/>workflow catalog<br/>[README.md]"]
  node_idea_generation["Idea gen<br/>workflow<br/>[idea-generation.md]"]
  node_idea_validation["Idea validate<br/>workflow<br/>[idea-validation.md]"]
  node_market_deep_dive["Market dive<br/>workflow"]
  node_pivot_optimization["Pivot optimize<br/>workflow"]
end

subgraph group_group_skills["Skill Library"]
  node_trend_analysis["Trend analysis<br/>skill<br/>[SKILL.md]"]
  node_competitor_mapper["Competitors<br/>skill<br/>[SKILL.md]"]
  node_desire_evaluator["Desire eval<br/>skill<br/>[SKILL.md]"]
  node_pricing_wtp["Pricing WTP<br/>skill<br/>[SKILL.md]"]
  node_distribution_analysis["Distribution<br/>skill<br/>[SKILL.md]"]
  node_retention_predictor["Retention<br/>skill<br/>[SKILL.md]"]
  node_cac_modeler["CAC model<br/>skill<br/>[SKILL.md]"]
  node_tam_sam_som["TAM/SAM/SOM<br/>skill<br/>[SKILL.md]"]
  node_idea_scoring["Idea score<br/>skill<br/>[SKILL.md]"]
  node_pivot_engine["Pivot engine<br/>skill<br/>[SKILL.md]"]
  node_decision_memo["Decision memo<br/>skill<br/>[SKILL.md]"]
  node_background_interviewer["Founder interview<br/>skill<br/>[SKILL.md]"]
  node_segmentation_profiler["Segmentation<br/>skill<br/>[SKILL.md]"]
  node_weakness_detection["Weaknesses<br/>skill<br/>[SKILL.md]"]
end

subgraph group_group_memory["Memory Layer"]
  node_memory_store[("Memory<br/>persistent storage")]
  node_user_profile["User profile<br/>context file"]
  node_ideas_store[("Ideas<br/>artifact store")]
  node_market_insights[("Market insights<br/>artifact store")]
  node_core_desires["Core desires<br/>context file"]
end

subgraph group_group_evidence["Evidence & Outputs"]
  node_market_sources{{"Market sources<br/>evidence sources"}}
  node_tiktok(("TikTok<br/>source"))
  node_reddit(("Reddit<br/>source"))
  node_x_twitter(("X/Twitter<br/>source"))
  node_app_store(("App Store<br/>source"))
  node_google_trends(("Google Trends<br/>source"))
end

node_user_chat(("User chat<br/>chat runtime"))

node_user_chat -->|"Claude path"| node_claude_md
node_user_chat -->|"Codex path"| node_agents_md
node_user_chat -->|"Cursor path"| node_cursor_rules
node_claude_md -->|"routes to"| node_workflows_readme
node_agents_md -->|"routes to"| node_workflows_readme
node_cursor_rules -->|"routes to"| node_workflows_readme
node_workflows_readme -->|"includes"| node_idea_generation
node_workflows_readme -->|"includes"| node_idea_validation
node_workflows_readme -->|"includes"| node_market_deep_dive
node_workflows_readme -->|"includes"| node_pivot_optimization
node_idea_generation -->|"starts with"| node_background_interviewer
node_idea_generation -->|"uses"| node_trend_analysis
node_idea_generation -->|"ends with"| node_idea_scoring
node_idea_validation -->|"uses"| node_trend_analysis
node_idea_validation -->|"uses"| node_competitor_mapper
node_idea_validation -->|"uses"| node_pricing_wtp
node_idea_validation -->|"uses"| node_distribution_analysis
node_idea_validation -->|"uses"| node_retention_predictor
node_idea_validation -->|"uses"| node_cac_modeler
node_idea_validation -->|"concludes with"| node_idea_scoring
node_idea_validation -->|"writes"| node_decision_memo
node_market_deep_dive -->|"uses"| node_trend_analysis
node_market_deep_dive -->|"uses"| node_competitor_mapper
node_market_deep_dive -->|"uses"| node_tam_sam_som
node_market_deep_dive -->|"uses"| node_segmentation_profiler
node_pivot_optimization -->|"uses"| node_weakness_detection
node_pivot_optimization -->|"uses"| node_pivot_engine
node_pivot_optimization -->|"writes"| node_decision_memo
node_trend_analysis -->|"pulls from"| node_market_sources
node_competitor_mapper -->|"pulls from"| node_app_store
node_trend_analysis -->|"pulls from"| node_tiktok
node_trend_analysis -->|"pulls from"| node_reddit
node_trend_analysis -->|"pulls from"| node_x_twitter
node_trend_analysis -->|"pulls from"| node_google_trends
node_idea_generation -->|"persists to"| node_memory_store
node_idea_validation -->|"persists to"| node_memory_store
node_market_deep_dive -->|"persists to"| node_memory_store
node_pivot_optimization -->|"persists to"| node_memory_store
node_memory_store -->|"contains"| node_user_profile
node_memory_store -->|"contains"| node_ideas_store
node_memory_store -->|"contains"| node_market_insights
node_memory_store -->|"contains"| node_core_desires
node_decision_memo -->|"outputs"| node_ideas_store

click node_claude_md "https://github.com/maxkmet/idea-validation-agents/blob/main/CLAUDE.md"
click node_agents_md "https://github.com/maxkmet/idea-validation-agents/blob/main/AGENTS.md"
click node_cursor_rules "https://github.com/maxkmet/idea-validation-agents/blob/main/.cursor/rules"
click node_workflows_readme "https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/README.md"
click node_idea_generation "https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/idea-generation.md"
click node_idea_validation "https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/idea-validation.md"
click node_market_deep_dive "https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/market-deep-dive.md"
click node_pivot_optimization "https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/pivot-optimization.md"
click node_trend_analysis "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/trend-analysis/SKILL.md"
click node_competitor_mapper "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/competitor-mapper/SKILL.md"
click node_desire_evaluator "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/desire-evaluator/SKILL.md"
click node_pricing_wtp "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/pricing-and-wtp/SKILL.md"
click node_distribution_analysis "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/distribution-analysis/SKILL.md"
click node_retention_predictor "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/retention-predictor/SKILL.md"
click node_cac_modeler "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/cac-modeler/SKILL.md"
click node_tam_sam_som "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/tam-sam-som-builder/SKILL.md"
click node_idea_scoring "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/idea-scoring/SKILL.md"
click node_pivot_engine "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/pivot-engine/SKILL.md"
click node_decision_memo "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/decision-memo/SKILL.md"
click node_background_interviewer "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/user-background-interviewer/SKILL.md"
click node_segmentation_profiler "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/user-segmentation-profiler/SKILL.md"
click node_weakness_detection "https://github.com/maxkmet/idea-validation-agents/blob/main/skills/weakness-detection/SKILL.md"
click node_memory_store "https://github.com/maxkmet/idea-validation-agents/tree/main/memory"
click node_ideas_store "https://github.com/maxkmet/idea-validation-agents/tree/main/memory/ideas"
click node_market_insights "https://github.com/maxkmet/idea-validation-agents/tree/main/memory/market_insights"
click node_core_desires "https://github.com/maxkmet/idea-validation-agents/blob/main/memory/extra-context/core-human-desires.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_md,node_agents_md,node_cursor_rules toneBlue
class node_workflows_readme,node_idea_generation,node_idea_validation,node_market_deep_dive,node_pivot_optimization toneAmber
class node_trend_analysis,node_competitor_mapper,node_desire_evaluator,node_pricing_wtp,node_distribution_analysis,node_retention_predictor,node_cac_modeler,node_tam_sam_som,node_idea_scoring,node_pivot_engine,node_decision_memo,node_background_interviewer,node_segmentation_profiler,node_weakness_detection toneMint
class node_memory_store,node_user_profile,node_ideas_store,node_market_insights,node_core_desires toneRose
class node_market_sources,node_tiktok,node_reddit,node_x_twitter,node_app_store,node_google_trends toneIndigo
class node_user_chat toneNeutral
```

## Components

### Platform Adapters

Entry-point instructions for different chat runtimes.

- [CLAUDE.md](https://github.com/maxkmet/idea-validation-agents/blob/main/CLAUDE.md): adapter · Claude Code entry-point instructions. · `CLAUDE.md`
- [AGENTS.md](https://github.com/maxkmet/idea-validation-agents/blob/main/AGENTS.md): adapter · Codex entry-point instructions. · `AGENTS.md`
- [Cursor rules](https://github.com/maxkmet/idea-validation-agents/blob/main/.cursor/rules): adapter · Cursor rule set for tool behavior and workflow routing. · `.cursor/rules`

### Workflows

User-facing pipelines that orchestrate analysis stages.

- [Workflow guide](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/README.md): workflow catalog · Overview of the repository's pipeline-first operating model. · `workflows/README.md`
- [Idea gen](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/idea-generation.md): workflow · Founder interview, trend mining, and initial scoring. · `workflows/idea-generation.md`
- [Idea validate](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/idea-validation.md): workflow · Full validation pipeline from research to decision. · `workflows/idea-validation.md`
- [Market dive](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/market-deep-dive.md): workflow · Deeper category and competitor analysis sequence. · `workflows/market-deep-dive.md`
- [Pivot optimize](https://github.com/maxkmet/idea-validation-agents/blob/main/workflows/pivot-optimization.md): workflow · Explores alternative directions and pivot options. · `workflows/pivot-optimization.md`

### Skill Library

Reusable analysis modules invoked by workflows.

- [Trend analysis](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/trend-analysis/SKILL.md): skill · Finds demand signals across market sources. · `skills/trend-analysis/SKILL.md`
- [Competitors](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/competitor-mapper/SKILL.md): skill · Maps competing products and gaps. · `skills/competitor-mapper/SKILL.md`
- [Desire eval](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/desire-evaluator/SKILL.md): skill · Assesses user pain and motivation strength. · `skills/desire-evaluator/SKILL.md`
- [Pricing WTP](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/pricing-and-wtp/SKILL.md): skill · Estimates willingness to pay and price bands. · `skills/pricing-and-wtp/SKILL.md`
- [Distribution](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/distribution-analysis/SKILL.md): skill · Assesses acquisition and channel opportunity. · `skills/distribution-analysis/SKILL.md`
- [Retention](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/retention-predictor/SKILL.md): skill · Predicts repeat usage and stickiness. · `skills/retention-predictor/SKILL.md`
- [CAC model](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/cac-modeler/SKILL.md): skill · Models customer acquisition cost. · `skills/cac-modeler/SKILL.md`
- [TAM/SAM/SOM](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/tam-sam-som-builder/SKILL.md): skill · Builds market size estimates. · `skills/tam-sam-som-builder/SKILL.md`
- [Idea score](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/idea-scoring/SKILL.md): skill · Combines signals into a ranked score. · `skills/idea-scoring/SKILL.md`
- [Pivot engine](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/pivot-engine/SKILL.md): skill · Generates alternative product directions. · `skills/pivot-engine/SKILL.md`
- [Decision memo](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/decision-memo/SKILL.md): skill · Writes the final recommendation artifact. · `skills/decision-memo/SKILL.md`
- [Founder interview](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/user-background-interviewer/SKILL.md): skill · Collects reusable founder and context details. · `skills/user-background-interviewer/SKILL.md`
- [Segmentation](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/user-segmentation-profiler/SKILL.md): skill · Profiles target users and segments. · `skills/user-segmentation-profiler/SKILL.md`
- [Weaknesses](https://github.com/maxkmet/idea-validation-agents/blob/main/skills/weakness-detection/SKILL.md): skill · Finds gaps and failure modes in ideas. · `skills/weakness-detection/SKILL.md`

### Memory Layer

Filesystem-backed persistent context and artifacts.

- [Memory](https://github.com/maxkmet/idea-validation-agents/tree/main/memory): persistent storage · Long-lived filesystem state reused across sessions. · `memory`
- **User profile**: context file · Reusable founder context and preferences.
- [Ideas](https://github.com/maxkmet/idea-validation-agents/tree/main/memory/ideas): artifact store · Per-idea session artifacts and outputs. · `memory/ideas`
- [Market insights](https://github.com/maxkmet/idea-validation-agents/tree/main/memory/market_insights): artifact store · Category research outputs kept for reuse. · `memory/market_insights`
- [Core desires](https://github.com/maxkmet/idea-validation-agents/blob/main/memory/extra-context/core-human-desires.md): context file · Background framework for human motivation analysis. · `memory/extra-context/core-human-desires.md`

### Evidence & Outputs

External market signals and generated deliverables.

- **Market sources**: evidence sources · External research inputs used to infer demand and distribution.
- **TikTok**: source · Creative Center and trend signals.
- **Reddit**: source · Community pain points and discussion signals.
- **X/Twitter**: source · Live market chatter and creator signals.
- **App Store**: source · Competitor presence and review signals.
- **Google Trends**: source · Search demand and interest over time.

### Other components

- **User chat**: chat runtime · Interactive surface in Claude Code, Codex CLI, or Cursor.

## Connections

- User chat → CLAUDE.md: Claude path · Claude Code reads the repo instructions.
- User chat → AGENTS.md: Codex path · Codex CLI reads the repo instructions.
- User chat → Cursor rules: Cursor path · Cursor applies rule files for behavior routing.
- CLAUDE.md → Workflow guide: routes to · Platform adapter points into workflow selection.
- AGENTS.md → Workflow guide: routes to · Platform adapter points into workflow selection.
- Cursor rules → Workflow guide: routes to · Platform rules activate the workflow catalog.
- Workflow guide → Idea gen: includes · Catalog exposes the available pipelines.
- Workflow guide → Idea validate: includes · Catalog exposes the available pipelines.
- Workflow guide → Market dive: includes · Catalog exposes the available pipelines.
- Workflow guide → Pivot optimize: includes · Catalog exposes the available pipelines.
- Idea gen → Founder interview: starts with · Idea generation begins with founder/context interview.
- Idea gen → Trend analysis: uses · Then mines demand signals for candidate ideas.
- Idea gen → Idea score: ends with · Produces scored ideas.
- Idea validate → Trend analysis: uses · Validation starts with trend research.
- Idea validate → Competitors: uses · Maps competing offerings and gaps.
- Idea validate → Pricing WTP: uses · Tests willingness to pay.
- Idea validate → Distribution: uses · Assesses acquisition and channels.
- Idea validate → Retention: uses · Estimates repeat usage and stickiness.
- Idea validate → CAC model: uses · Models acquisition cost.
- Idea validate → Idea score: concludes with · Combines signals into a final score.
- Idea validate → Decision memo: writes · Produces the recommendation artifact.
- Market dive → Trend analysis: uses · Category research starts with market signals.
- Market dive → Competitors: uses · Expands competitor understanding.
- Market dive → TAM/SAM/SOM: uses · Sizes the market.
- Market dive → Segmentation: uses · Defines relevant customer segments.
- Pivot optimize → Weaknesses: uses · Finds failure modes in the current concept.
- Pivot optimize → Pivot engine: uses · Generates alternative directions.
- Pivot optimize → Decision memo: writes · Summarizes pivot recommendations.
- Trend analysis → Market sources: pulls from · Trend work depends on external evidence.
- Competitors → App Store: pulls from · Uses app listings and review signals.
- Trend analysis → TikTok: pulls from · Uses creative trend signals.
- Trend analysis → Reddit: pulls from · Uses community demand signals.
- Trend analysis → X/Twitter: pulls from · Uses social chatter signals.
- Trend analysis → Google Trends: pulls from · Uses search interest signals.
- Idea gen → Memory: persists to · Stores session outputs for later reuse.
- Idea validate → Memory: persists to · Stores artifacts and scores.
- Market dive → Memory: persists to · Stores research outputs.
- Pivot optimize → Memory: persists to · Stores pivot artifacts.
- Memory → User profile: contains · Reusable founder context.
- Memory → Ideas: contains · Idea-specific artifacts.
- Memory → Market insights: contains · Category research artifacts.
- Memory → Core desires: contains · Shared context for desire analysis.
- Decision memo → Ideas: outputs · Decision memos and related artifacts are saved with ideas.