git:20260826.886162a to git:20261012.52f340e

68 added, 256 removed. Audit A to A.

- # Product Development Framework

- AI-assisted product development from vague idea to technical spec. Guides users through structured UX research, hypothesis formation, and prototype planning.

- ## Repo Structure

- The framework prompts are bundled inside the plugin at `plugin/prompts/` so the

- plugin is self-contained and distributable. Skills, commands, and the subagent

- reference them via `${CLAUDE_PLUGIN_ROOT}/prompts/...` (ADR 0011).

- ```

- plugin/prompts/

- ├── 01_ux_research/

- │ ├── 00_fuzzy_front_end/ # Phase 00: Idea capture + exploration

- │ ├── 01_define_problem/ # Phase 01: Problem statement + persona

- │ ├── 02_objectives/ # Phase 02: Core objective + metrics

- │ ├── 03_solution_hypothesis/# Phase 03: Solution concept + hypothesis

- │ ├── 04_user_flow/ # Phase 04: User flow + screens

- │ ├── 05_prototype/ # Phase 05: Prototype scoping + test design

- │ └── 06_post_test_synthesis/# Phase 06: Test analysis + evaluation

- ├── 02_tech_requirements/ # Tech spec: data models, APIs, business rules, NFRs

- ├── 07_ux_optimization/ # Reverse pass: extract artifacts from an existing product (ADR 0013)

- ├── 03_tool_selection_setup/ # Environment and tooling (Tier 3, not in active workflow)

- ├── 04_bridge_to_architecture/ # Architecture transition prompts (Tier 3)

- └── 05_implementation_docs/ # Implementation planning (Tier 3)

- ```

- Non-framework reference material (build guides, IDE rules, portfolio prompts)

- remains at repo root under `prompts/dev/` and is not part of the plugin bundle.

- **Frontmatter schema** (each prompt file):

- ```yaml

- name: kebab-case-name

- run: always | entry_point | context_gated

- run_when: [plain-English condition, only for context_gated]

- produces: artifact_name

- requires: [dependency_artifact_1, dependency_artifact_2]

- tier: 1 | 2

- ```

- **Prompt body structure:** `<system_context>` sets your role, instructions define the output, `<constraints>` set boundaries, `<example>` shows quality. Template variables use `{{artifact_name}}` syntax. See ADR 0001 for full schema.

- ## Workflow Paths

- Four skills (ADR 0004, amended by ADR 0013), each covering a contiguous set of phases:

- ### product-ideation (Phases 00-03)

- Entry points: `/idea`, `/problem`

- |--------|-----|----------|----------|

- ### product-flow (Phases 04-06)

- |--------|-----|----------|----------|

- ### tech-spec (Tech Requirements)

- Entry point: `/spec`. Spawns the Tech Spec Writer subagent (`plugin/agents/tech-spec-writer.md`). Requires design artifacts: `solution_concept`, `user_flow`.

- ### ux-optimization (Reverse Pass, ADR 0013)

- Entry point: `/optimize`. Audits an **existing** product: extracts artifacts from its repository (via the read-only `ux-extractor` subagent), validates them with the owner, then gap-analyzes into a prioritized optimization spec. Extracted artifacts carry `mode`/`provenance`/`confidence`/`validation_status` frontmatter; `context.json` carries `"mode": "reverse"`.

- |--------|-----|----------|----------|

- After validation, the registry matches forward-pass Phases 00-04 and the standard downstream (product-flow, tech-spec, `/compile`) applies unchanged. Visual-layer defects are handed off to a design-system audit, not itemized in the spec.

- ## Run Conditionality (ADR 0006)

- - **`always`**: Run unconditionally in sequence when reached.

- - **`entry_point`**: Pick one based on user's starting context. `capture_idea` for a specific product idea, `explore_problem` for domain-level exploration. Both produce `initial_concept`. Never run both.

- - **`context_gated`**: Check `run_when` condition before including. Skip with a note about why it was skipped and when to revisit.

- Context gates:

- - `identify-screens-states`: "Digital product with UI" — skip for services, processes, physical products

- - `synthesize-test-patterns`: "User has completed testing" — skip until real observations exist

- - `evaluate-hypothesis`: "`test_insights` exists in context" — skip until post-test synthesis complete

- - `define-api-endpoints`: "Software product with client-server architecture" — skip for hardware, processes

- When a gate is unclear, ask the user.

- ## Tier Model (ADR 0006)

- Default to **Tier 1** (quick exploration, 5-10 min). Only the prompts listed above run at Tier 1.

- **Escalation signals** (switch to Tier 2):

- - User provides detailed, multi-paragraph responses

- - User asks to "go deeper", "analyze further", "be more thorough"

- - User explicitly requests comprehensive analysis

- **De-escalation signals** (stay at / return to Tier 1):

- - User says "that's enough", "move on", "keep it simple"

- - Short, confirmatory responses

- When escalating:

- 1. Update `tier` to 2 in `context.json`

- 2. Check the current phase directory for Tier 2 prompts (files with `tier: 2` in frontmatter)

- 3. Present them as optional branches: "We can go deeper here. Available: [list with one-line descriptions]. Which would be most useful, or should we continue the main sequence?"

- 4. Let the user pick which Tier 2 prompts to run — do not run all automatically

- 5. After each selected Tier 2 prompt, return to the main Tier 1 sequence

- Never auto-escalate to Tier 3. Only run all prompts in a phase when explicitly requested.

- ---

- ## Context Registry

- All project state persists in `.product-dev/` in the working directory (`context.json` registry + `artifacts/*.md` + `learnings.jsonl` + compiled `spec-package/`).

- **The canonical operations reference is bundled with the plugin: [`plugin/docs/registry-operations.md`](plugin/docs/registry-operations.md)** — directory layout, `context.json` schema (including `inputs` provenance), the five operations (`createProject`, `setArtifact`, `getArtifact`, `getStatus`, `checkGate`), process learnings, template variable resolution (including the `{{name?}}` optional-placeholder syntax), status display with staleness annotation, the Session Resume Algorithm, and re-entry rules. Skills reference it via `${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` so it resolves in consumer projects (ADR 0011). Read that file before performing registry operations; do not work from memory of it.

- ## Prompt Execution Flow

- When the user starts a conversation or continues an existing project:

- 1. **Check for existing project**: Read `.product-dev/context.json`. If it exists, greet with a brief status summary and suggest next steps. If not, offer to start a new project.

- 2. **Determine entry point**: Based on user's input:

- - Vague idea for a specific product → `capture_idea` (entry_point)

- - Domain interest, no specific product idea → `explore_problem` (entry_point)

- - Has a problem but no statement → `create_problem_statement` (skip Phase 00)

- - Request for specs → check prerequisites for tech-spec path

- - Continuing from previous session → resume using the algorithm below

- ### Session Resume Algorithm

- Canonical algorithm: `plugin/docs/registry-operations.md` § Session Resume Algorithm. Summary: read `context.json`, determine the active skill from `current_phase`, find the next unexecuted prompt whose `requires` are all satisfied (evaluating `run_when` gates), and resolve `{{variables}}` from disk — never from conversation history.

- 3. **Execute prompt**:

- - Read the prompt file from `${CLAUDE_PLUGIN_ROOT}/prompts/...`

- - Resolve `{{variables}}` from the context registry

- - Present the prompt's output to the user conversationally — not as a formatted dump

- - Write the artifact via `setArtifact()`

- 4. **Advance**: After each prompt, check `run` type of the next prompt in sequence:

- - `always` → proceed automatically with brief transition

- - `context_gated` → check `run_when` condition, skip if not met

- - If crossing a workflow path boundary (e.g., ideation → flow), confirm with the user

- 5. **Tier check**: After each user response, evaluate escalation/de-escalation signals. Adjust tier if warranted.

- ### Checkpoints

- After every 2-3 prompts, offer navigation:

- - "Does this capture what you're thinking?" (validation)

- - "Should we go deeper on [X] or move forward?" (navigation)

- - "I see [N] threads here. Which feels most promising?" (prioritization)

- ### Re-entry and Iteration

- Canonical rules: `plugin/docs/registry-operations.md` § Re-entry and Staleness. Summary: revisions increment `version`; staleness is computed from `inputs` maps, not guessed; always ask before regenerating downstream artifacts.

- ---

- ## Subagent Invocation

- ### Tech Spec Writer

- **When:** User reaches the tech-spec path or explicitly asks for technical specifications.

- **Prerequisites:** Verify `solution_concept` and `user_flow` exist in the registry.

- **How:** Spawn `plugin/agents/tech-spec-writer.md` with the Agent tool. The subagent reads artifacts from `.product-dev/artifacts/` directly and writes specs back to the registry.

- **After return:** Present specs one area at a time (data models, API contracts, business rules, NFRs), rating each 0-10 and naming what a 10 would contain. Walk the Decision Log the subagent appended to `technical_spec` (Taste decisions as a batch, User-Challenges one at a time — the design artifacts are the default). Then run the adversarial review loop (5 dimensions, max 3 iterations, convergence guard) per the tech-spec skill.

- ---

- ## Plugin

+ # product-dev — contributor guide

- The framework is packaged as a Claude Code plugin at `plugin/`. Structure follows ADR 0008. Install locally with `claude plugin install --plugin-dir ./plugin`.

+ This repo builds a Claude Code plugin: an AI-assisted product development

+ framework that takes a vague idea to a technical spec. This file governs work

+ **on the repo**. How the plugin behaves for its users is defined inside

+ `plugin/`, which ships without this file (ADR 0011, ADR 0019).

- ```

- plugin/

- ├── .claude-plugin/plugin.json # Manifest: name, description, version, author

- ├── commands/ # 6 commands (/idea, /problem, /spec, /compile, /summary, /optimize)

- │ ├── idea.md

- │ ├── problem.md

- │ ├── spec.md

- │ ├── compile.md

- │ ├── summary.md

- │ └── optimize.md

- ├── skills/ # 5 skills (4 workflows + status)

- │ ├── product-ideation/SKILL.md

- │ ├── product-flow/SKILL.md

- │ ├── tech-spec/SKILL.md

- │ ├── ux-optimization/SKILL.md

- │ └── status/SKILL.md

- ├── agents/ # 2 subagents

- │ ├── tech-spec-writer.md

- │ └── ux-extractor.md

- ├── prompts/ # Bundled prompt library (framework workflow)

- │ ├── 01_ux_research/

- │ ├── 02_tech_requirements/

- │ ├── 03_tool_selection_setup/

- │ ├── 04_bridge_to_architecture/

- │ └── 05_implementation_docs/

- └── scripts/ # Bundled compile pipeline

- ├── compile_spec.py

- ├── validate_spec.py

- ├── generate_handoff.py

- └── requirements.txt

- ```

+ Keep this file short and made of pointers. If something here restates a skill,

+ a prompt, or an ADR, delete the restatement and link to the source.

- **Commands** are entry points — `/idea`, `/problem`, `/spec` dispatch to workflow skills. `/compile` assembles artifacts into a validated spec package. `/summary` assembles a consolidated project brief.

- **Skills** own the conversational UX — prompt sequencing, tier escalation, registry operations, checkpoints. Also accessible as `/product-dev:product-ideation`, `/product-dev:product-flow`, `/product-dev:tech-spec`, `/product-dev:status`.

- **Agents** are isolated workers — the tech-spec-writer takes design artifacts and produces structured specs.

+ ## Two modes

- The plugin bundles its prompt library and compile scripts under `plugin/prompts/` and `plugin/scripts/`, referenced via `${CLAUDE_PLUGIN_ROOT}` so the bundle is self-contained and resolves regardless of the user's working directory (ADR 0011). The context registry (`.product-dev/`) lives in the user's project directory, not in the plugin.

+ - **Working on the repo** (the default): editing prompts, skills, checks, ADRs,

+ docs. The rules below apply. Do not start the product workflow or report

+ `.product-dev/` status unless asked.

+ - **Using the plugin here** (someone runs `/idea`, `/spec`, `/optimize`, …):

+ the invoked skill is the instruction set. Follow it, not this file.

- ### Deliverables

+ ## Where things are defined

- The workflow produces three deliverables:

+ | Topic | Source of truth |

+ |-------|-----------------|

+ | Decisions, their status, what enforces them | [ADR index](docs/adrs/README.md), then the record itself |

+ | Workflow sequences, gates, checkpoints, tier escalation | each skill: [product-ideation](plugin/skills/product-ideation/SKILL.md), [product-flow](plugin/skills/product-flow/SKILL.md), [tech-spec](plugin/skills/tech-spec/SKILL.md), [ux-optimization](plugin/skills/ux-optimization/SKILL.md), [status](plugin/skills/status/SKILL.md) |

+ | Context registry, session resume, staleness, learnings | [registry-operations.md](plugin/docs/registry-operations.md) |

+ | What runs when (`run`, `run_when`, `tier`, `requires`) | each prompt's frontmatter under [plugin/prompts/](plugin/prompts) |

+ | Prompt authoring, plugin development, ADR process | [CONTRIBUTING.md](CONTRIBUTING.md) |

+ | Spec package format | [spec-package-schema.md](docs/spec-package-schema.md) |

+ | Checks, hooks, graduation | [checks/README.md](checks/README.md) |

- - **Project Brief** (`/summary`) — Assembles design artifacts (problem, persona, hypothesis, flows, prototype scope) into a single document. The "why and what."

- - **Technical Spec** (`/spec`) — Data models, API contracts, business rules, NFRs. The "how."

- - **Spec Package** (`/compile`) — Compiled output directory with three layers: context (prose), spec (YAML), governance (PRD + ADRs). Validated for cross-reference integrity. Agent-consumable. The "build from this."

+ ## Rules for changes

- Working artifacts live in `.product-dev/artifacts/`. The compiled spec package lives in `.product-dev/spec-package/`. See `docs/spec-package-schema.md` for the full schema (ADR 0010).

+ 1. **Find the decision first.** Open the ADR index, then read the record

+ including its `## Amendment` sections and anything listed under "Amended

+ by". Later text overrides earlier text.

+ 2. **A request that conflicts with an Accepted ADR is not a dead end.** Say

+ which record it conflicts with, then either do the compliant version or

+ draft the change as an appended amendment or a new ADR with status

+ `Proposed`, and ask. Do not make the conflicting change and adjust the

+ record to match.

+ 3. **ADRs are append-only.** Append a dated section or write a new numbered

+ ADR. A new ADR that changes an older one says "amends ADR NNNN", and the

+ older one gets an appended note naming it. Then run

+ `python checks/adr_index.py --write`.

+ 4. **Never make a finding go away by editing the check, its config, or a

+ limit.** Fix the content. If the check is wrong, say so and propose the fix

+ as its own change. Demoting a check or raising a word limit is the owner's

+ decision and gets logged in the owning ADR.

+ 5. **The plugin must stand alone.** Anything under `plugin/` references

+ bundled files through `${CLAUDE_PLUGIN_ROOT}` and never depends on this

+ file, on `docs/`, or on repo-root paths.

+ 6. **The component set is decided.** Adding or removing a command, skill, or

+ subagent needs an amendment to ADR 0004 first.

+ 7. **Before pushing:** `python checks/run_checks.py --ci` and

+ `python -m unittest discover -s checks/tests`. A `block` finding fails CI

+ and stops the session from finishing; the message names the ADR and the

+ remedy.

+ 8. **Hook kill-switches are the owner's.** If a guard blocks you, take the

+ move its message offers or stop and ask.

+ 9. Deferred work goes to GitHub issues, not into docs. Commits are

+ conventional (`type(scope): description`). User-visible changes get a

+ CHANGELOG line.

- ---

+ ## Runtime rules that exist only here

- ## Decisions & ADR References

+ These govern plugin behaviour but were never moved into `plugin/`, so plugin

+ users do not get them. Tracked in

+ [issue #62](https://github.com/clownware/product-dev/issues/62); until it

+ closes, apply them when running the workflow in this repo.

- - Prompt frontmatter schema: ADR 0001

- - Context registry and state management: ADR 0003

- - Skill/subagent decomposition (3 skills, 1 subagent): ADR 0004

- - Progressive disclosure and tiered engagement: ADR 0006

- - Plugin architecture: ADR 0008

- - Prompt enhancement pattern: ADR 0009

- - Spec package as compilation target: ADR 0010

- - Plugin self-containment (bundled prompts/scripts/registry canon via `${CLAUDE_PLUGIN_ROOT}`): ADR 0011

- - ADR enforcement architecture (checks/run_checks.py, guard hooks): ADR 0012

- - UX optimization reverse pass (ux-optimization skill, /optimize): ADR 0013

- - Live-site audit mode + objective metrics prompt: ADR 0014

- - Runtime audit mode (locally runnable products): ADR 0015

- - gstack-derived patterns (interrogation gates, candidate directions, input provenance): ADR 0016

- - gstack-derived patterns, second wave (quality loops, decision classification, scope walk, learnings): ADR 0017

- - Ops dashboard audit signal (CI reports `audit.finding_count`): ADR 0018

+ - **Tier escalation is offered, not applied.** On an escalation signal, set

+ `tier` to 2 in `context.json`, list the current phase's `tier: 2` prompts

+ with one-line descriptions, and let the user pick. After each picked prompt,

+ return to the Tier 1 sequence.

+ - **Never auto-escalate to Tier 3.** Run every prompt in a phase only on

+ explicit request.

+ - **When a `context_gated` condition is unclear, ask the user.**

+ - **Entry points are exclusive.** `capture_idea` and `explore_problem` both

+ produce `initial_concept`; run one, never both.