Product Development Framework

A Claude Code plugin that compiles fuzzy product ideas into validated, agent-consumable specification packages.

What It Does

Takes a product idea and walks you through structured product thinking — problem definition, persona, hypothesis, user flows — then compiles the output into a spec package that an implementation agent (Claude Code, Cursor, etc.) can build from without guessing.

"I have an idea for a      →  Guided conversation  →  spec-package/
 tea tracking app"             (14 prompts)              ├── manifest.yaml
                                                         ├── context/     (why)
                                                         ├── spec/        (what)
                                                         ├── docs/        (decisions)
                                                         └── CLAUDE.md    (handoff)

The spec package has three layers:

• Context (prose) — problem, persona, hypothesis, concept. Gives the implementation agent the why.
• Specification (YAML) — entities, flows, screens, endpoints, rules, constraints. Gives the agent the what with cross-referenced IDs and type-safe schemas.
• Governance (markdown) — compiled PRD and extracted ADRs. The decisions and rationale, including what was explicitly excluded.

A validation pipeline checks referential integrity across all spec files before the package is marked as ready.

Prerequisites

• Claude Code — CLI, Desktop app, or VS Code extension
• Python 3.9+ — optional; only /compile uses it (to run the bundled plugin/scripts/compile_spec.py). The ideation/flow/spec workflow and /summary brief work without it. If Python is absent, /compile explains and points you to /summary and the raw artifacts instead of failing with a traceback.
• pyyaml — auto-installed by /compile from plugin/scripts/requirements.txt when Python is present

Install

From the Clownware marketplace, inside Claude Code:

/plugin marketplace add clownware/plugins
/plugin install product-dev@clownware

Or from a terminal:

claude plugin marketplace add clownware/plugins
claude plugin install product-dev@clownware

To run it from a checkout of this repo without installing, for development:

claude --plugin-dir ./plugin

Works in Claude Code CLI, Desktop app, and VS Code extension.

Usage

Commands

Command	What It Does
/idea	Start from a product idea — "a tea tracking app"
/problem	Start from a problem domain — "specialty tea enthusiasts waste tea"
/spec	Generate technical specs (data models, API, business rules, NFRs)
/compile	Assemble artifacts into a validated spec package + handoff instruction
/summary	Generate a consolidated project brief
/optimize	Audit an existing product and build a prioritized UX optimization spec
/product-dev:status	Show project progress and suggest next steps

Typical Flow

/idea tea tracking app        → Captures concept, defines problem, creates persona,
                                 forms hypothesis (Phases 00-03, ~20 min)

                               → Maps user flow, identifies screens, scopes prototype
                                 (Phase 04, ~15 min)

/spec                          → Generates data models, API contracts, business rules,
                                 constraints as structured YAML (Tech Spec, ~20 min)

/compile                       → Assembles spec-package/, runs 20 validation checks,
                                 generates CLAUDE.md handoff instruction (~30 sec)

Then copy spec-package/ and CLAUDE.md into a fresh project directory and point an implementation agent at it.

Tiered Engagement

Default is Tier 1 (quick exploration, ~60 min total). The framework escalates to Tier 2 when you give detailed responses or ask to go deeper.

Repository Structure

├── plugin/                            # Claude Code plugin (self-contained, installable)
│   ├── .claude-plugin/plugin.json     # Plugin manifest
│   ├── commands/                      # 6 commands (/idea, /problem, /spec, /compile, /summary, /optimize)
│   ├── skills/                        # 5 skills (4 workflows + status)
│   ├── agents/                        # 2 subagents (tech-spec-writer, ux-extractor)
│   ├── prompts/                       # Bundled prompt library
│   │   ├── 01_ux_research/            # Prompts: phases 00-06
│   │   ├── 02_tech_requirements/      # Tech spec prompts: 4 areas + consolidation
│   │   └── 03-05_*/                   # Tool setup, architecture bridge, impl docs
│   └── scripts/                       # Bundled compile pipeline
│       ├── compile_spec.py            # Spec package compiler
│       ├── validate_spec.py           # 20-check cross-reference validator
│       ├── generate_handoff.py        # CLAUDE.md handoff generator
│       └── requirements.txt           # Python deps (pyyaml)
│
├── prompts/dev/                       # Non-framework reference material (not bundled)
│   ├── build guides/                  # Stack starter guides
│   ├── ide_rules/                     # IDE configuration prompts
│   └── portfolio/                     # Portfolio case-study prompts
│
├── scripts/                           # Dev/test material (not bundled)
│   ├── archive/                       # One-time migration utilities
│   ├── test-chain.md                  # End-to-end test doc
│   └── test-registry.md               # Registry test doc
│
├── examples/tea-tracker/              # Reference spec package (test fixture)
│   ├── context.json                   # Sample registry
│   ├── artifacts/                     # Sample working artifacts (12 files)
│   ├── spec-package/                  # Compiled output (16 files)
│   └── CLAUDE.md                      # Generated handoff instruction
│
├── skills-claude-ai/                  # Claude.ai Agent Skill ports (ideation + flow)
│   ├── product-ideation/              # SKILL.md + bundled prompts (phases 00-03)
│   └── product-flow/                  # SKILL.md + bundled prompts (phases 04-06)
│
└── docs/
    ├── spec-package-schema.md         # Spec package YAML schema (v1.0.0)
    ├── adrs/                          # Architecture Decision Records
    └── updates/                       # PRD v3, refactor roadmap, enhancement guides

Spec Package Schema

See docs/spec-package-schema.md for the full schema definition:

• entities.yaml — Data model with typed fields, constraints, indexes
• flows.yaml — User journey with screen + API call references per step
• screens.yaml — UI inventory with content elements, data sources, actions
• endpoints.yaml — API contracts with request/response schemas
• rules.yaml — Business logic as IF/THEN pseudocode with enforcement locations
• constraints.yaml — Performance targets, security config, prototype scope

All IDs are cross-referenced. The validation pipeline checks 20 rules across referential integrity, completeness, and consistency.

Architecture Decisions

Decisions are recorded as ADRs. The index — one row per record with its status, the checks that enforce it, and what amended it — is generated from the records themselves: docs/adrs/README.md.

ADR Enforcement

Every ADR declares its testable consequences in an appended ## Enforcement section, verified by a check suite:

python checks/run_checks.py

Warnings report; only graduated (block) checks fail CI or block a session. See checks/README.md for graduation and exclusions, and ADR 0012 for the architecture.

Contributing

See CONTRIBUTING.md for prompt authoring standards, plugin development, and the ADR process.

Acknowledgments

The interrogation, premise-challenge, quality-loop, decision-classification, scope-walk, and process-learnings patterns (ADRs 0016–0017) were adapted from Garry Tan's gstack (MIT).

License

Apache 2.0. See LICENSE.