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

claude plugin install --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
/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/                      # 5 commands (/idea, /problem, /spec, /compile, /summary)
│   ├── skills/                        # 4 skills (3 workflows + status)
│   ├── agents/                        # 1 subagent (tech-spec-writer)
│   ├── 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/                          # 17 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

Key decisions are documented as ADRs in docs/adrs/:

ADR	Decision
0001	YAML frontmatter as canonical prompt metadata
0002	MCP prompt packaging (deferred in favor of plugin)
0003	File-based context registry at .product-dev/
0004	3 skills + 1 subagent decomposition
0005	Prompt enhancement schema
0006	Progressive disclosure and tiered engagement
0007	JSON index deprecation
0008	Plugin as delivery vehicle
0009	Prompt Enhancement Pattern v2
0010	Spec package as compilation target
0011	Plugin self-containment via ${CLAUDE_PLUGIN_ROOT}
0012	ADR enforcement architecture
0013	UX optimization reverse pass (/optimize)
0014	Live-site audit mode + objective metrics
0015	Runtime audit mode for locally runnable products
0016	gstack patterns: interrogation, candidate directions, provenance
0017	gstack patterns: quality loops, decision classification, scope walk, learnings

ADR Enforcement

Every ADR declares its testable consequences in an appended ## Enforcement section, verified by a warn-only 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.