Reference/Idea-to-Build-Skill-Proposal.md
idea-to-build — Repeatable Guided Exploratory Build Pipeline
Proposed meta-skill that codifies the process used in Session 1 to produce the Crawler Factory plan + 13 specs + verification cycle. Designed so any future "operator brings idea + dossier" session follows the same disciplined path without relying on agent self-direction.
Status: Proposal v1. First pass — operator (2026-04-30 round 2) explicitly noted this is one shape, not THE shape. Variations to evaluate are listed in §"Variations + Research Directions" below.
Source artifacts: Process-Reflection-Verbatim-Transcript.md, Process-Reflection-Verbatim-Transcript-Round-2.md, Process-Documentation-Session-1.md, Lessons-Learned-Session-1.md — read those first.
Larger context: this skill is Module 1 (Planning) of a 4-module product-creation methodology — see Projects/Vibe-Coded-Product-Methodology/README.md for the OUTER vision (GitHub-distributable, commercializable methodology covering Plan → Design → Build → Test).
Why this skill exists
The operator stated the requirement bluntly:
"you don't follow instructions 90% of the time, 99.9999% of the time you do not follow instructions. You assume."
A repeatable process has to ENFORCE the path, not rely on agent discipline. Today's Crawler Factory session worked because the operator manually pushed back at every assumption. That doesn't scale. The operator wants:
"Anytime I have an idea and I want to do it, I will first do my initial research, I will bring things and all that, and then sort of prepare the initial dossier for you, and then launch you. You will take the dossier, start learning, and then start questioning me, and then we will collectively devise..."
So this skill is fundamentally about guided collaboration with hard gates between phases. Every gate forces: 1. Operator review before progression 2. Empirical validation before commitment 3. Re-verification after fixes
The 9-phase pipeline
┌──────────────────────────────────────────────────────────────────┐
│ │
│ 1. DOSSIER INTAKE ← operator brings idea + sources │
│ ↓ │
│ 2. CONTEXT LOADING ← agent reads, asks clarifying Qs │
│ ↓ │
│ 3. INITIAL SKETCH ← rough plan; operator review │
│ ↓ │
│ 4. ASSUMPTION SURFACING + RESEARCH ← empirical validation │
│ ↓ │
│ 5. PLAN FREEZE ← vault commit; SOPs applied │
│ ↓ │
│ 6. CONTRACT LOCK ← cross-cluster types frozen │
│ ↓ │
│ 7. SPEC GENERATION ← parallel agents per cluster │
│ ↓ │
│ 8. MULTI-AXIS VERIFY ← closed re-verify loop │
│ ↓ │
│ 9. BUILD HANDOFF ← Sonnet 4.6 teams-mode │
│ │
└──────────────────────────────────────────────────────────────────┘
Each phase has explicit inputs, outputs, gates, sub-skills invoked, and exit criteria.
Phase 1 — Dossier Intake
Input: operator's idea + dossier (paths to: prior plans, knowledge sources, related code, references, constraints).
Required dossier shape (rejected if missing any element): - Idea: one paragraph minimum, what + why + who - UX walk-through: step-by-step user journey for the primary flow - Knowledge sources: at least 3 pointers (vault docs, prior plans, existing code, external refs) - Constraints: model preference, vault destination, repo branch, deadlines if any - Definition of done: what "shipped v1" means
Skill action: validates dossier shape against this rubric. If incomplete, lists what's missing and HALTS until operator fills gaps.
Sub-skills invoked: none — this is intake validation.
Exit gate: structured dossier present and validated.
Phase 2 — Context Loading + Clarifying Questions
Skill action:
1. Reads every dossier source.
2. Builds a private "what I now know" summary.
3. Surfaces 3-7 specific clarifying questions to the operator (via AskUserQuestion). Examples:
- "Your dossier says X; does that mean Y or Z?"
- "I see two possible interpretations of [constraint]; which is right?"
- "What's the priority between [tradeoff A] and [tradeoff B]?"
4. Captures answers verbatim into a Context-Locked.md artifact.
Sub-skills invoked: none — the questioning is direct.
Exit gate: all clarifying questions answered. Operator confirms "context locked."
Critical principle: the agent MUST ask questions even if it thinks it understands. The operator stated agents assume too much. Forced questioning surfaces assumptions.
Phase 3 — Initial Sketch
Skill action: invokes superpowers:writing-plans to produce a v0 plan. Plan covers the entire pipeline from architecture to phasing to risks. Saved to vault.
Sub-skills invoked:
- superpowers:writing-plans
Output: 00-Plan-v0.md in vault project directory.
Exit gate: operator review (mandatory). Operator pushback expected and welcomed. Skill explicitly prompts: "Where does this plan make assumptions you want me to validate?"
Phase 4 — Assumption Surfacing + Empirical Research
THIS IS THE PHASE THAT IS CURRENTLY MISSING FROM EVERY EXISTING SKILL. Today's session showed it's where the most architectural value is created.
Skill action:
1. Re-reads the v0 plan.
2. Programmatically extracts every "assumption" claim — phrases like "most sites...", "typically...", "we assume...", any percentage, any architectural premise.
3. Lists them as a numbered Assumption Register.
4. For each assumption, dispatches a research agent with explicit empirical-validation scope:
- Sites/sources to fetch
- Specific data points to extract
- Expected output format
5. Aggregates findings into a Reality-Catalog.md artifact.
6. Cross-references back to v0 plan: which assumptions were validated, which were corrected, which were refuted.
7. Generates a v1 plan with empirical numbers replacing intuition.
Sub-skills invoked:
- Agent of subagent_type Explore for parallel research dispatch
- WebFetch for direct fetches
- superpowers:writing-plans for plan revision
Required research dimensions (the operator's actual feedback expanded into a checklist): - Industry / vertical patterns — research the spectrum (B2B SaaS, B2C retail, manufacturing, healthcare, government, media, education, etc.) - Technology adoption — what % of sites use X? (cite sources like Web Almanac, BuiltWith, Crunchbase) - Standards and protocols — what specs exist (schema.org, sitemaps.org, RFCs)? what % adoption? - Real-world examples — fetch 5-10 representative sites per pattern; document what's actually present - Edge cases — WAF, rate limits, anti-bot, paywalls, auth walls, JS-only rendering
Exit gate: operator confirms the Reality Catalog adequately covers their concern. If operator says "but you didn't research X" — loop back, dispatch more research.
Critical principle: v0 plan is hypothesis. v1 plan is grounded in citations. Move only to v1 ONCE the citation density per architectural claim is acceptable.
Phase 5 — Plan Freeze + SOP Application
Skill action:
1. Final plan revision incorporating Reality Catalog.
2. Saves to vault Projects/<ProjectName>/00-Plan.md.
3. Mirrors to local repo docs/planning/<date>-<project>.md.
4. Marks plan version as v1.0-frozen.
5. Invokes standards-coding / standards-testing / standards-writing against the plan to ensure SOP-compliant in narrative, structure, and any code-shaped sections.
6. Generates Plan-Update-Audit-Trail.md mapping every change between v0 and v1 to its empirical or operator-driven justification.
Sub-skills invoked:
- superpowers:writing-plans (final revision)
- standards-coding, standards-testing, standards-writing (compliance audit on plan content)
Exit gate: operator explicit "plan frozen" approval. Plan committed in git.
Critical principle: the plan is the source of truth from this point. Specs derive from it; build derives from specs; nothing derives from the operator's verbal updates without going back through Phase 4 first.
Phase 6 — Contract Lock (NEW — addresses parallel-author drift)
This phase did NOT exist in Session 1 and was the root cause of the V1 verification's 7 Critical interface mismatches.
Skill action:
1. Decomposes the frozen plan into N clusters (each cluster = one cohesive subsystem, max ~12 clusters).
2. For each cluster, identifies its EXPORTS (types, function signatures, HTTP response shapes, SSE event shapes, etc.) and IMPORTS (what it consumes from other clusters).
3. Generates a single Contracts.ts (or contracts.md if not code-targeted) artifact with EVERY cross-cluster boundary type locked.
4. Operator reviews Contracts.ts. This is a hard gate.
Sub-skills invoked: none — this is structural decomposition.
Output: Contracts.ts (or equivalent) in vault project directory. Every cluster spec consumes this as a fixed import.
Exit gate: operator approves Contracts.ts. Cluster authors may NOT modify it without going back through Phase 5.
Critical principle (lesson from Session 1): parallel cluster authors will drift if they each invent their own interfaces. Lock the contracts BEFORE parallel work starts.
Phase 7 — Spec Generation (Parallel)
Skill action:
1. Dispatches one parallel agent per cluster (max 12 concurrent, batched if more).
2. Each agent receives:
- Frozen plan
- Contracts.ts (locked imports)
- Cluster brief (the slice of plan tasks this cluster owns)
- SOP rules (translated to target language)
3. Each agent invokes superpowers:writing-plans to produce a TDD-bite-sized spec.
4. Each agent self-reviews against the writing-plans format and the Contracts.ts before reporting "done."
Sub-skills invoked:
- superpowers:writing-plans (per cluster, parallel)
Output: N cluster specs in Engineering-Specs/.
Exit gate: all N specs return without errors. Move to Phase 8 immediately — DO NOT declare ready.
Phase 8 — Multi-Axis Verification with Closed Re-Verify Loop
THIS IS THE OTHER MISSING SKILL. Today's session composed it from 4 parallel agents + manual orchestration over 3 verification cycles.
Skill action — single invocation runs:
1. Plan coverage axis — for every plan requirement, point to the spec that covers it. Gap = Critical.
2. Cross-spec interface drift — extract export/import graph; verify exports match consumer expectations against Contracts.ts. Drift = Critical.
3. SOP compliance per spec — invoke standards-coding, standards-testing, standards-writing per spec.
4. Research incorporation — verify empirical findings from Phase 4 made it into specs.
5. Hallucinated dependencies — check every referenced symbol resolves to a definition.
6. Aggregates findings into VERIFICATION-REPORT-V<N>.md.
7. Closed re-verify loop: if Critical or Important issues found, dispatch fix agents, then RE-RUN the entire verification. Halt only when 0 Critical AND 0 Important. Maximum 3 iterations; if not clean by V3, escalate to operator.
Sub-skills invoked:
- superpowers:requesting-code-review (overridden for spec review; OR new spec-compliance-review skill if proposed)
- standards-coding, standards-testing, standards-writing
- Agent of subagent_type superpowers:code-reviewer for cross-cluster review
Output: VERIFICATION-REPORT-V1.md, optionally V2/V3, plus SOP audit reports.
Exit gate: verdict is "Ready to build" with 0 Critical, 0 Important.
Critical principle (lesson from Session 1): fix passes can introduce new drift (B14 was a NEW Critical introduced by V1's fix pass). The re-verify loop is non-negotiable.
Phase 9 — Build Handoff
Skill action:
1. Confirms verification verdict is clean.
2. Produces a Build-Handoff.md artifact:
- Build order (cluster dependency graph)
- Recommended model (Sonnet 4.6 for build, Opus for deep architectural questions during build)
- Smoke test protocol (from Phase 5 plan §9)
- Known suggestions to address during build (non-blocking items from VStatus.md.
4. Optionally dispatches superpowers:subagent-driven-development to start the build.
Sub-skills invoked:
- (optional) superpowers:subagent-driven-development
Output: Build-Handoff.md, updated Status, build dispatched OR ready for operator to dispatch.
Exit gate: operator confirms model switch and start build OR holds for separate session.
What this skill is NOT
- It is not a fully autonomous "give me an idea and walk away" pipeline. The operator is required at gate reviews in Phases 1, 2, 3, 4, 5, 6, and 9.
- It is not a replacement for
writing-plans,standards-*, orcode-reviewer. It ORCHESTRATES them. - It does not skip the empirical research phase. Phase 4 is non-skippable.
- It does not pretend to be a single skill. It is a meta-skill that may need to be a plugin or a chain of sub-skills with hard gates between them.
Implementation options
Option A — Single canonical skill superpowers:idea-to-build
Pros: one entry point. Easy to invoke. Documentation in one place. Cons: very large; complex to author; hard to maintain.
Option B — Plugin with multiple sub-skills
plugins/idea-to-build/
├── SKILL.md (orchestrator, defines the 9 phases)
├── phase-1-dossier-intake.md
├── phase-2-context-loading.md
├── phase-3-initial-sketch.md
├── phase-4-empirical-research.md ← KEY new sub-skill
├── phase-5-plan-freeze.md
├── phase-6-contract-lock.md ← KEY new sub-skill
├── phase-7-spec-generation.md
├── phase-8-multi-axis-verify.md ← KEY new sub-skill
└── phase-9-build-handoff.md
Pros: each phase is its own skill. Authorable independently. Easier to test. Cons: orchestration discipline depends on the parent skill.
Option C — A Claude Code "playbook" — declarative YAML/Markdown spec that the harness executes
Pros: deterministic. Same playbook runs on Opus or Sonnet. Easy to version. Cons: requires harness work; less flexible for mid-process pivots.
Recommendation: Option B. Each phase is a real skill; the orchestrator lives at the top. Hard gates between phases enforce operator review. This is closest to how the existing superpowers: skills are structured.
What the operator should bring to launch this skill
When the next idea comes in, the operator should prepare a structured dossier that satisfies Phase 1 intake. Template:
# Idea Dossier — <Project Name>
## Idea
<One paragraph: what + why + who. Example: "Build a Crawler Factory that takes
a website URL and auto-builds Algolia crawlers per content domain. For ops
team. Replaces manual dashboard work.">
## UX Walk-Through
1. Operator enters URL at /admin/factory
2. Factory streams sitemap discovery
3. ...
## Knowledge Sources
- `~/path/to/SESSION.md`
- vault `Projects/<related>/`
- vault `Standards/`
- prior plan: <path>
- existing code: <paths>
- external refs: <URLs>
## Constraints
- Model preference: Opus 4.7 1M for planning, Sonnet 4.6 for build
- Vault destination: Projects/<NewProjectName>/
- Repo branch: <branch>
- Deadline: <if any>
## Definition of Done (v1)
- <bullet list of "ship" criteria>
## Areas where I want you to push hardest
- "Validate against complex sites: BMW, Adobe, multi-brand corporates"
- "Don't assume schema.org coverage — research it"
- ...
## Hard nos
- No Supabase
- No Redis for new features
- ...
The skill validates this template at intake. Anything missing → halt, ask, complete.
Maintenance notes
When future sessions go through this pipeline:
- Each session produces its own Process-Documentation.md capturing what worked and didn't.
- Lessons learned per session feed into SOP/skill updates (see Lessons-Learned-Session-1.md for the pattern).
- The pipeline itself is versioned. v1 is what's described here. v2 may add new gates, remove redundant ones, or change tooling based on session feedback.
Operator's verbatim ask (for reference)
"I want you to record every single thing that we have done today, step by step, and follow it, and then how can we convert this into a proper guided exploratory repeatable process? Anytime I have an idea and I want to do it, I will first do my initial research, I will bring things and all that, and then sort of prepare the initial dossier for you, and then launch you. You will take the dossier, start learning, and then start questioning me, and then we will collectively devise, okay, and brave, and bring up the idea, break it up and expand it, and build it, and then research it, and then do all that. Help me put together a system. Help me put together a skill. Help me put together the structure."
This document is the structure. The 9 phases are the system. The skill is idea-to-build (or whatever name we pick).
Variations + Research Directions (added per operator feedback 2026-04-30 round 2)
The operator stated: "This process can have variations, so I want you to explore and find variations and bring some recommendations."
The 9-phase linear-gated pipeline above is Variation A (the default recommendation). Five other shapes worth evaluating before locking v1 of the methodology:
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 process. Best for highly uncertain problem spaces, R&D, products without established patterns. Drawback: harder to coordinate; risk of perpetual churn.
Variation C — Continuous flow with parallel research/validation tracks
Plan ─┬→ Design ─┬→ Build ─┬→ Test ─┬→ Ship
└ Research → └ Validate → └ Smoke ┘
Research and validation run alongside the main flow continuously. Best for mature product lines, well-understood domains, fast iteration cycles. Drawback: more orchestration overhead.
Variation D — Skill-graph (DAG) instead of linear
Operator picks a goal; the methodology computes the minimum dependency graph of skills and runs them in parallel where possible. Best for experienced teams who want flexibility. 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: - 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 configurations
- 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 B/C/D/E/F as alternative configurations the operator can opt into via a methodology config file.
Research directions the operator should green-light before v2
- Compare to existing frameworks. BMad Method, Agentic Eng, Cursor's
.cursorrules, GitHub's spec-kit — what do they do differently? Where are they weaker? Where stronger? - Eval harness design. How do we measure that the methodology actually reduces rework? Need: a metric (issues caught at verification vs. issues caught at runtime — the lower-the-better ratio).
- Operator burden study. How long does the dossier take to write? Is it shorter than the time saved? Without this number, the methodology is faith-based.
- Skill-router prototype. A skill that, given a task description, recommends the right canonical skill OR flags "no canonical skill — use these primitives." Would have prevented 3 misfires in Session 1.
- Failure-mode catalog. Systematically capture every failure pattern across multiple sessions (parallel-author drift was Session 1's; what's Session 2's?). Patterns become methodology updates.
Next steps
- Operator reviews this proposal — pushes back on phase ordering, gate criteria, or sub-skill choices.
- Operator picks Variation (A default, or another) for v1 default.
- Operator picks implementation Option (A single skill vs. B plugin with sub-skills vs. C declarative playbook).
- Operator picks commercial path (open-core vs SaaS-first) — see
Projects/Vibe-Coded-Product-Methodology/README.mdfor that decision. - The skill or plugin gets authored — likely in
~/.claude/plugins/idea-to-build/. - Module 2 (Design) is the methodology's first self-test: use Module 1 to plan Module 2.
- Next idea the operator brings = first real test of the full pipeline. Lessons feed v2.