Project

Vibe-Coded-Product-Methodology

Vault: myos Path: Vibe-Coded-Product-Methodology

README.md

Vibe-Coded Product Creation Methodology

The OUTER vision. A distributable, GitHub-able, sellable end-to-end methodology for building software products with Claude Code (or comparable agentic harnesses). The Crawler Factory was the first session that exercised it. Algolia's RC3 Phoenix product family is one application of it. This project captures the methodology itself as a standalone product.

Status: Vision capture. Not yet implemented as a distributable repo or skill plugin. Source: Operator (Arijit Chowdhury), Crawler Factory planning session 2026-04-30. Vault adjacency: Sibling to Projects/Crawler-Factory/ (the first concrete session) and Projects/Algolia-Central/RC3-Phoenix-Product-Family-Vision.md (the first commercial application).

The thesis in one paragraph

Anyone building software solutions with Claude Code goes through the same painful loop: vague idea → premature plan → drifting build → broken artifacts → manual rework. The methodology being captured here turns that loop into a deterministic, gated pipeline. Operator brings an idea + dossier; the system runs them through structured phases (intake, context, sketch, empirical research, freeze, contract lock, spec, multi-axis verify, build, smoke). Each phase has a hard gate the operator approves. The outputs are auditable, parallelizable, and reproducible. Vibe-coded product creation, but with engineering discipline baked in.

What this is, distinct from existing tools

What people use today	What this provides
`superpowers:writing-plans` (one good plan)	An orchestrator that USES `writing-plans` plus 8 other phases
Cursor / Copilot vibe-coding (fast, undisciplined)	Fast AND disciplined — structure prevents the drift that kills vibe-coded projects at scale
BMad Method, Agentic Eng frameworks	A specific pipeline + sub-skills + hard gates, opinionated about empirical research and re-verify loops
ChatGPT one-shot codegen	Multi-phase, multi-agent, multi-vault-artifact, audit-trailed

The differentiator is the empirical research phase + the contract lock phase + the closed re-verify loop. None of those exist as canonical skills today. Without them, parallel agent generation drifts. The Crawler Factory session proved this empirically — V1 fix pass introduced a NEW Critical (B14) that V2 caught. Without the re-verify loop, B14 ships to build.

Three audiences (commercial framing)

Solo / indie devs vibe-coding side projects — they get a free GitHub repo with the methodology + sub-skills. Plug into Claude Code. Their projects get more done with less rework.
Engineering teams shipping with Claude Code in production — they get a paid tier with team features (shared dossiers, vault sync, audit dashboards, SOP customization, methodology versioning).
Companies using Claude Code as a product-development substrate — they get consulting / managed onboarding to adopt the methodology org-wide. Algolia would be the first customer; we build it for ourselves first, then sell it.

The free tier is the loss leader; the paid tier and the consulting are the revenue. Same shape as classic open-core (HashiCorp, GitLab, Mattermost).

The methodology — modules

Each module is its own packagable unit. The modules compose into the full pipeline. Operators can adopt the whole thing or just the modules they need.

Module	What it does	Status
1. Planning	Dossier → context → sketch → empirical research → freeze. Produces a frozen plan in vault.	Designed in `Projects/Crawler-Factory/Idea-to-Build-Skill-Proposal.md` (v1). 9-phase pipeline.
2. Design	Plan → architecture spec → UI/UX design (with `frontend-design` and `aesthetic-*` skills) → design pre-mortem. Produces a design pack.	Pre-design. Operator referenced "I am going to be adding stuff for design as well using cloud design and whatnot."
3. Build	Design → contract lock → spec generation → multi-axis verify → multi-agent execution. Produces shipped code.	Partial — Crawler Factory's spec-generation + verify cycle exercised this.
4. Test	Build → unit tests → integration tests → smoke tests → SOP audits → release-readiness gate. Produces a "ready" verdict.	Pre-design. Existing `standards-testing` skill is one input.

The operator stated: "Your first module is planning. In your planning, you do these three things. You feed it, and then the system will do this. Here is how you design, and then I am going to be adding stuff for design as well using cloud design and whatnot. Here's how you would build it, and here is how you will test it."

So the methodology is a 4-module pipeline: Plan → Design → Build → Test. Each module has its own sub-skills, harness, and operator gates.

Variations to research before locking the methodology

The operator explicitly asked for variations: "This process can have variations, so I want you to explore and find variations and bring some recommendations."

Variation A — Fully linear gated pipeline (current proposal)

Plan → Design → Build → Test

Each phase blocks until operator approves. Closest to traditional waterfall but gated by AI agents.

Best for: large products, multi-engineer teams, regulated industries. Drawback: slow for small features.

Variation B — Spiral / iterative

Plan_v0 → quick Build → quick Test → learn → Plan_v1 → fuller Build → ...

Each loop is small. Empirical learning informs the next. Closer to RUP/spiral.

Best for: highly uncertain problem spaces, R&D, products without established patterns. Drawback: harder to coordinate across teams; risk of perpetual churn.

Variation C — Continuous flow with parallel tracks

Plan ─┬→ Design ─┬→ Build ─┬→ Test ─┬→ Ship
       └ Research → └ Validate → └ Smoke ┘

Research and validation tracks run alongside the main flow. Findings feed in continuously.

Best for: mature product lines, well-understood domains, fast iteration cycles. Drawback: harder to manage parallelism; more orchestration overhead.

Variation D — Skill-graph (DAG) instead of linear

Operator picks the goal; the methodology computes the minimum dependency graph of skills and runs them in parallel where possible.

Best for: experienced teams who want flexibility; CI/CD-style automation. Drawback: harder to teach; less predictable to first-time users.

Variation E — Specification-first vs. test-first vs. design-first

The order Plan → Design → Build → Test isn't sacred. Some teams do: - Test-first (TDD-extreme): write tests, then design, then build (tests are the spec) - Design-first (Apple-style): UX-driven, then build the engineering to support it - Spec-first (current default): formal spec, then design + build derive

The methodology should let operators pick which style their product wants.

Variation F — Operator role variations

Solo operator (one person, one Claude Code session) — current Crawler Factory shape
Team operator (multiple people review the same dossier; one drives Claude Code) — needs collaboration tools
Async operator (operator drops dossier overnight, agents work, operator reviews in morning) — needs async-friendly hard gates
Distributed operator (different operators own different modules) — needs handoff artifacts between modules

Recommended starting point

Ship Variation A (linear gated) as the v1 default. It's the easiest to teach and hardest to drift from. Add Variations B/C/D/E/F as alternative configurations the operator can opt into via the methodology config file.

What the GitHub repo would contain

vibe-coded-methodology/
├── README.md (the pitch + quick-start)
├── LICENSE (MIT or Apache-2.0; permissive)
├── modules/
│   ├── 1-planning/
│   │   ├── README.md (the planning module spec)
│   │   ├── skills/ (sub-skills, with .md/.yaml definitions)
│   │   └── examples/ (worked examples — Crawler Factory anonymized)
│   ├── 2-design/
│   ├── 3-build/
│   └── 4-test/
├── harness/
│   ├── claude-code/ (install scripts for ~/.claude/plugins/)
│   ├── cursor/ (for Cursor users)
│   └── generic/ (provider-agnostic version)
├── templates/
│   ├── dossier.md (the dossier template)
│   ├── contracts.ts (the cross-cluster contract template)
│   └── status.md (the project status template)
├── docs/
│   ├── theory.md (why this exists, the parallel-author drift problem, etc.)
│   ├── case-studies/ (Crawler Factory + future Connector Factory + …)
│   └── variations.md (Variations A-F documented)
└── tooling/
    ├── eval/ (eval harness — does the methodology actually reduce rework?)
    └── metrics/ (how to measure your project's adherence to the methodology)

The case studies folder is the proof. Crawler Factory becomes the first case study — the methodology produced a clean plan, 13 specs, 3-pass verification cycle, in one session. With anonymization, it's a public artifact.

Operator-stated commercial path

"This methodology can be solved today. My explanation is Algolia-centric, but you take the methodology. If we build it, we build it in scales, in a format. We put it on GitHub. We can create a company out of it. We can sell that. That is the crux of the matter, bro."

Two paths to evaluate:

Open-source first, monetize later. GitHub repo, MIT license, community contributions. Monetize via paid features, hosted version, SaaS dashboard, or consulting.
Closed-source product, marketed loud. SaaS platform that wraps Claude Code with this methodology baked in. Per-seat pricing.

Open-source first is more aligned with how Claude Code itself ships. It's also the path that builds reputation faster.

What we learn from the Crawler Factory session that feeds back

The operator asked: "What do we learn from it? What can we learn more? What can we keep in our stuff and enhance our methodology?"

From Projects/Crawler-Factory/Lessons-Learned-Session-1.md, seven patterns: 1. Parallel-author drift is the dominant failure mode → methodology mandates Contract Lock phase 2. Skill ecosystem gap between code-review and content-review → methodology defines a new spec-compliance skill 3. Language equivalence cost in CodingSOPs → methodology proposes a Python↔TS↔Go↔Rust map 4. Em-dash + chained-colon mechanical-replacement artifacts → methodology codifies replacement rules in WritingSOPs 5. Data-driven extensibility worked spectacularly → methodology adds this as a CodingSOPs pattern 6. Closed re-verify loop is non-negotiable → methodology enforces it 7. Plan persistence in vault is the audit trail → methodology requires it as Phase 5 output

Each of these is a methodology-level upgrade. They don't just live in the Crawler Factory project; they go into the methodology's core.

Future sessions feed more lessons. The methodology versions explicitly: v1, v1.1, v2, etc. Each lesson that holds across multiple sessions becomes a permanent module rule.

Immediate next steps

Operator reviews this README — pushes back on the 4-module decomposition, the variations, the commercial framing.
Pick a Variation (A vs B vs C vs D vs E vs F) for v1 default.
Decide open-core vs SaaS-first commercial path.
Author Module 1 (Planning) as a real plugin under ~/.claude/plugins/idea-to-build/ or as a standalone GitHub repo. The design is in Projects/Crawler-Factory/Idea-to-Build-Skill-Proposal.md.
Use Module 1 to plan Module 2 (Design) — meta-application proves the methodology works.
Anonymize Crawler Factory as Case Study #1 for the docs.

Risks to flag now

"Yet another framework" fatigue. The Claude Code ecosystem already has BMad Method, Agentic Eng, etc. Differentiation must be sharp.
Methodology overhead vs. velocity. Vibe-coding's appeal is speed. Hard gates can feel like bureaucracy. Variations B/E/F mitigate this but don't erase it.
Skill ecosystem dependency. Methodology depends on superpowers:*, standards-*, etc. If those skills change, the methodology breaks. Need version pinning.
Operator skill required. A bad dossier produces bad output regardless of how good the methodology is. May need a "dossier scaffolding wizard" as a separate sub-skill.
Anthropic could ship something competing. Anthropic has the ecosystem; if they decide to build their own canonical "build a product" skill, this methodology becomes redundant. The hedge: get adoption first, position as community-owned and provider-agnostic.

Connection back to Algolia

The methodology is generic. The Algolia RC3 Phoenix product family (Projects/Algolia-Central/RC3-Phoenix-Product-Family-Vision.md) is one application. We build the methodology for ourselves to ship Algolia. We then commercialize the methodology. The Algolia product family is the proof that the methodology delivers — the first case study.

If the methodology actually works, the Connector Factory should ship faster than the Crawler Factory. If it does, that's evidence for the commercial pitch.