maxkmet/idea-validation-agents

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.