From b3e3c043c53bbf546d8ebe8dc4bb31881658941a Mon Sep 17 00:00:00 2001 From: Chris Pezza <153260989+chrispezza@users.noreply.github.com> Date: Mon, 12 Oct 2026 14:11:25 -0400 Subject: [PATCH] feat(plugin): ship the workflow rules that lived only in CLAUDE.md Four rules about plugin behaviour existed only in this repo's CLAUDE.md, so plugin users never received them (issue #62). - Add a Workflow Rules section to the bundled registry-operations doc: tier escalation is offered and the user picks, never auto-escalate to Tier 3, ask when a context_gated condition is unclear, entry points are exclusive - Point all four workflow skills at it; product-ideation no longer inserts Tier 2 prompts on a signal, product-flow and tech-spec gain the procedure - Remove the unshipped-rules section from CLAUDE.md - Append amendments to ADRs 0006 and 0019; bump the plugin to 0.5.1 Closes #62 Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + CLAUDE.md | 22 ++--------- ...rogressive-disclosure-tiered-engagement.md | 13 +++++++ docs/adrs/0019-claude-md-contributor-guide.md | 17 +++++++++ docs/adrs/README.md | 4 +- plugin/.claude-plugin/plugin.json | 2 +- plugin/docs/registry-operations.md | 37 ++++++++++++++++++- plugin/skills/product-flow/SKILL.md | 2 + plugin/skills/product-ideation/SKILL.md | 6 +-- plugin/skills/tech-spec/SKILL.md | 2 + plugin/skills/ux-optimization/SKILL.md | 2 +- 11 files changed, 81 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 67ca992..28c8511 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `skills-claude-ai/` — Claude.ai Agent Skill ports of product-ideation and product-flow (issue #12): bundled prompts with skill-relative paths, conversation-scoped artifact ledger with `product-dev-artifacts.md` export replacing the `.product-dev/` registry ### Changed +- Plugin 0.5.1: tier escalation is now offered, not applied, in every workflow skill. Four rules that existed only in this repo's `CLAUDE.md` ship in `plugin/docs/registry-operations.md` § Workflow Rules (offer Tier 2 prompts and let the user pick; never auto-escalate to Tier 3; ask when a gate condition is unclear; entry points are exclusive). `product-ideation` previously inserted Tier 2 prompts on a signal; `product-flow` and `tech-spec` had no escalation procedure (issue #62) - `CLAUDE.md` is now the contributor guide (ADR 0019): about 650 words of pointers and change rules, down from about 2,000 that restated the skills, the tier model, the plugin tree, and the ADR list. Four runtime rules that never shipped in the plugin stay in a labelled section pending issue #62 - PreToolUse guard: an ADR is protected only once it exists in `HEAD`, so a draft can be revised before its first commit - README: the hand-kept ADR table is replaced by a pointer to the generated index diff --git a/CLAUDE.md b/CLAUDE.md index 09cd029..cd3f782 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,7 +22,7 @@ a prompt, or an ADR, delete the restatement and link to the source. |-------|-----------------| | 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) | +| Context registry, session resume, staleness, learnings, and the workflow rules all skills share (tier escalation, unclear gates, entry points) | [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) | @@ -46,7 +46,8 @@ a prompt, or an ADR, delete the restatement and link to the source. 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 +5. **The plugin must stand alone.** A rule about how the plugin behaves goes + in `plugin/`, never only here. 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 @@ -60,20 +61,3 @@ a prompt, or an ADR, delete the restatement and link to the source. 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 - -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. - -- **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. diff --git a/docs/adrs/0006-progressive-disclosure-tiered-engagement.md b/docs/adrs/0006-progressive-disclosure-tiered-engagement.md index 1d3cd61..adba42f 100644 --- a/docs/adrs/0006-progressive-disclosure-tiered-engagement.md +++ b/docs/adrs/0006-progressive-disclosure-tiered-engagement.md @@ -174,3 +174,16 @@ stated in full only in CLAUDE.md's "Runtime rules that exist only here" section. `product-ideation/SKILL.md` says to insert the Tier 2 prompts, and `product-flow` and `tech-spec` carry no escalation procedure. Issue #62 tracks moving it into the plugin. + +--- + +## Amendment (2026-10-12): Escalation procedure shipped in the plugin + +The gap above is closed (issue #62, owner decision). The procedure — on an +escalation signal, set `tier` to 2, present the phase's Tier 2 prompts as +optional branches, run only what the user picks, return to the Tier 1 +sequence; never auto-escalate to Tier 3 — is in +`plugin/docs/registry-operations.md` § Workflow Rules and referenced by all +four workflow skills. That section also carries two rules this ADR implied +but no shipped file stated: ask the user when a `context_gated` condition is +unclear, and run only one entry point. Plugin version 0.5.1. diff --git a/docs/adrs/0019-claude-md-contributor-guide.md b/docs/adrs/0019-claude-md-contributor-guide.md index 67412ba..64e6eeb 100644 --- a/docs/adrs/0019-claude-md-contributor-guide.md +++ b/docs/adrs/0019-claude-md-contributor-guide.md @@ -139,3 +139,20 @@ operations to everything else the file restated. ADR 0008 (component set), ADR 0006, ADR 0016, ADR 0017 (amended as above). - Issue #62 (unshipped runtime rules). - chrispezza/portfolio#106 (constitution-lift experiment record). + +--- + +## Amendment (2026-10-12): The unshipped rules shipped (issue #62) + +Owner decision: move the four rules into the plugin. They now live in +`plugin/docs/registry-operations.md` § Workflow Rules, which every workflow +skill references: tier escalation is offered and the user picks; never +auto-escalate to Tier 3; ask when a `context_gated` condition is unclear; +entry points are exclusive. `product-ideation` no longer says to insert Tier 2 +prompts, and `product-flow` and `tech-spec` now carry the escalation +procedure by reference. Plugin version 0.5.1. + +CLAUDE.md's "Runtime rules that exist only here" section is removed. Decision +§3 still stands for the future: a runtime rule may sit in CLAUDE.md only in a +section that names it as unshipped and links the issue tracking its move. At +this amendment there are none. diff --git a/docs/adrs/README.md b/docs/adrs/README.md index bc59416..be8f762 100644 --- a/docs/adrs/README.md +++ b/docs/adrs/README.md @@ -15,7 +15,7 @@ listed under "Amended by" override its earlier text. | [0003](0003-context-registry-state-management.md) | Context Registry and State Management | Accepted | `frontmatter-v2` (block), `placeholder-syntax` (block), `placeholder-resolvability` (block), `dependency-graph` (block) | 0013, 0016 | 2, latest 2026-10-12 | | [0004](0004-skill-subagent-decomposition.md) | Skill and Subagent Decomposition | Accepted | `component-census` (block) | 0013 | 1, latest 2026-10-12 | | [0005](0005-prompt-enhancement-schema.md) | Prompt Enhancement Schema | Deferred | `no-legacy` (block) | — | — | -| [0006](0006-progressive-disclosure-tiered-engagement.md) | Progressive Disclosure and Tiered Engagement | Accepted | `frontmatter-v2` (block) | 0019 | 2, latest 2026-10-12 | +| [0006](0006-progressive-disclosure-tiered-engagement.md) | Progressive Disclosure and Tiered Engagement | Accepted | `frontmatter-v2` (block) | 0019 | 3, latest 2026-10-12 | | [0007](0007-json-index-deprecation.md) | Deprecation of JSON Index Files and Stream Deck Document | Accepted | `no-legacy` (block) | — | — | | [0008](0008-plugin-architecture.md) | Plugin Architecture | Accepted | `manifest` (warn), `component-census` (block) | 0011 | 1, latest 2026-10-12 | | [0009](0009-prompt-enhancement-pattern.md) | Prompt Enhancement Pattern v2 | Accepted | `frontmatter-v2` (block), `name-uniqueness` (block), `body-structure` (block), `placeholder-syntax` (block), `word-limit` (warn) | — | 1, latest 2026-07-25 | @@ -28,7 +28,7 @@ listed under "Amended by" override its earlier text. | [0016](0016-gstack-derived-patterns.md) | gstack-Derived Patterns — Interrogation, Premise Challenge, Input Provenance | Accepted | no dedicated check | 0019 | 1, latest 2026-10-12 | | [0017](0017-gstack-derived-patterns-second-wave.md) | gstack-Derived Patterns, Second Wave — Quality Loops, Decision Classification, Scope Walk, Learnings | Accepted | no dedicated check | 0019 | 1, latest 2026-10-12 | | [0018](0018-ops-dashboard-audit-signal.md) | Report the Enforcement Suite's Finding Count to the Ops Dashboard | Accepted | no dedicated check | — | — | -| [0019](0019-claude-md-contributor-guide.md) | CLAUDE.md Is the Contributor Guide; Runtime Canon Lives in the Plugin | Accepted | `claude-md-scope` (warn) | — | — | +| [0019](0019-claude-md-contributor-guide.md) | CLAUDE.md Is the Contributor Guide; Runtime Canon Lives in the Plugin | Accepted | `claude-md-scope` (warn) | — | 1, latest 2026-10-12 | ## Reading the columns diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json index d1d505d..2e2cdd3 100644 --- a/plugin/.claude-plugin/plugin.json +++ b/plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "product-dev", "description": "AI-assisted product development framework. Guides from vague idea to technical spec through structured UX research, hypothesis formation, and prototype planning.", - "version": "0.5.0", + "version": "0.5.1", "author": { "name": "clownware" }, diff --git a/plugin/docs/registry-operations.md b/plugin/docs/registry-operations.md index 9c0cac7..23de15c 100644 --- a/plugin/docs/registry-operations.md +++ b/plugin/docs/registry-operations.md @@ -1,7 +1,8 @@ # Context Registry Operations Canonical reference for all `.product-dev/` state operations (ADR 0003, ADR 0011, -ADR 0016, ADR 0017). Skills and agents reference this file via +ADR 0016, ADR 0017), and for the workflow rules every workflow skill shares +(§ Workflow Rules; ADR 0006, ADR 0019). Skills and agents reference this file via `${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` — it ships with the plugin so the operations resolve in any consumer project. Perform every operation with file read/write; no MCP tools needed. @@ -95,6 +96,40 @@ When transitioning between workflow paths: 2. Check which have entries in `prompts_executed` 3. Report pass/fail with list of missing artifacts +## Workflow Rules + +Shared by all workflow skills (product-ideation, product-flow, tech-spec, +ux-optimization). A skill's own text adds detail; it does not override these. + +**Tier escalation is offered, never applied.** Default to Tier 1. When an +escalation signal appears (detailed multi-paragraph answers, "go deeper", +a request for comprehensive analysis): + +1. Update `tier` to 2 in `context.json`. +2. Find the current phase's Tier 2 prompts (the skill lists them; their + frontmatter says `tier: 2`). +3. Present them as optional branches with a one-line description each: "We can + go deeper here. Available: [list]. Which would be most useful, or should we + continue the main sequence?" +4. Run only the prompts the user picks. Do not run all of them automatically. +5. After each picked prompt, return to the Tier 1 sequence where it left off. + +On a de-escalation signal ("that's enough", "move on", short confirmations), +stay at or return to Tier 1. + +**Never auto-escalate to Tier 3.** Run every prompt in a phase only when the +user explicitly asks for the full set. + +**When a `context_gated` condition is unclear, ask the user.** Do not guess +whether a `run_when` condition holds. If it does not hold, skip the prompt and +say what was skipped and when to revisit it. + +**Entry points are exclusive.** Prompts with `run: entry_point` that produce +the same artifact are alternatives: pick one from the user's starting context +and never run the other. In the forward pass, `capture_idea` (a specific +product idea) and `explore_problem` (a domain interest) both produce +`initial_concept`. + ## Process Learnings `.product-dev/learnings.jsonl` captures how this user wants the *process* run — diff --git a/plugin/skills/product-flow/SKILL.md b/plugin/skills/product-flow/SKILL.md index fa63fa3..0f79621 100644 --- a/plugin/skills/product-flow/SKILL.md +++ b/plugin/skills/product-flow/SKILL.md @@ -48,6 +48,8 @@ When skipping a context-gated prompt, explain what the prompt would have covered ### Tier 2 Additional Prompts +Offered, never applied: on an escalation signal follow `${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` § Workflow Rules — present the current phase's prompts below as optional branches, run only what the user picks, then return to the Tier 1 sequence. Never auto-escalate to Tier 3. When a gate condition is unclear, ask the user. + - Phase 04: `identify-decision-points`, `plan-error-handling`, `user-entry-exit-points`, `validate-flow` - Phase 05: `choose-fidelity-level`, `identify-key-interactions`, `test-participant-goals`, `create-test-script` - Phase 06: `plan-next-iteration`, `explore-pivot-options`, `post-test-refine-problem` diff --git a/plugin/skills/product-ideation/SKILL.md b/plugin/skills/product-ideation/SKILL.md index dac19d4..a0608d2 100644 --- a/plugin/skills/product-ideation/SKILL.md +++ b/plugin/skills/product-ideation/SKILL.md @@ -38,13 +38,13 @@ All prompts are in `${CLAUDE_PLUGIN_ROOT}/prompts/01_ux_research/`. Read prompts | 5 | `03_solution_hypothesis/01_generate_solution_concept.md` | always | `solution_concept` | `problem_statement`, `core_objective` | | 6 | `03_solution_hypothesis/02_format_hypothesis_statement.md` | always | `hypothesis_statement` | `solution_concept` | -Pick entry point (1a or 1b) based on user input: +Pick exactly one entry point (1a or 1b) based on user input — never run both: - Specific product idea → `capture_idea` (1a) - Domain interest, no specific product → `explore_problem` (1b) ### Tier 2 Additional Prompts -When escalation signals detected, add these from the same phase: +When escalation signals are detected, offer these from the same phase and let the user pick: - Phase 00: `industry-analysis`, `competitive-analysis`, `explore-user-segments` - Phase 01: `analyze-problem`, `scope-problem`, `qualify-problem` @@ -113,7 +113,7 @@ De-escalate when: - User says "that's enough", "move on", "keep it simple" - Short, confirmatory responses -When escalating, insert the relevant Tier 2 prompts at the current phase position. Update `tier` in the registry. +When escalating, follow the shared procedure in `${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` § Workflow Rules: update `tier` in the registry, present the current phase's Tier 2 prompts as optional branches, run only what the user picks, then return to the Tier 1 sequence. Never auto-escalate to Tier 3. When a gate condition is unclear, ask. ## Context Registry diff --git a/plugin/skills/tech-spec/SKILL.md b/plugin/skills/tech-spec/SKILL.md index ec30661..75bf569 100644 --- a/plugin/skills/tech-spec/SKILL.md +++ b/plugin/skills/tech-spec/SKILL.md @@ -47,6 +47,8 @@ The subagent runs the tech requirements prompt sequence from `${CLAUDE_PLUGIN_RO ### Tier 2 Additional Prompts +Offered, never applied: on an escalation signal follow `${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` § Workflow Rules — present the relevant prompts below as optional branches and run only what the user picks. Never auto-escalate to Tier 3. When a gate condition is unclear, ask the user. + - Data models: `validate-data-model`, `identify-data-access-patterns`, `assess-data-volume-scaling` - API: `define-interface-boundaries`, `establish-api-standards`, `define-integration-requirements` - Business rules: `map-decision-logic`, `specify-calculations`, `define-authorization-rules` diff --git a/plugin/skills/ux-optimization/SKILL.md b/plugin/skills/ux-optimization/SKILL.md index 651b15d..91a251d 100644 --- a/plugin/skills/ux-optimization/SKILL.md +++ b/plugin/skills/ux-optimization/SKILL.md @@ -63,7 +63,7 @@ Standard operations (`${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` — rea ## Tier Behavior -Default Tier 1 is the sequence above. Escalation signals (ADR 0006) apply; at Tier 2 offer deeper branches per phase (e.g., live-site walkthrough of the deployed product if a browser is available, competitor-surface comparison). Never auto-escalate. +Default Tier 1 is the sequence above. Escalation signals (ADR 0006) apply, following the shared procedure in `${CLAUDE_PLUGIN_ROOT}/docs/registry-operations.md` § Workflow Rules; at Tier 2 offer deeper branches per phase (e.g., live-site walkthrough of the deployed product if a browser is available, competitor-surface comparison). Never auto-escalate. When a gate condition is unclear, ask the owner. ## Convergence and Handoff