@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/skills/build-prototype/references/vision2prompt/07_quality_rubric.md

@@ -0,0 +1,171 @@
+# 07 Quality Rubric
+
+Use this reference before marking `prompt_text_manifest.status` as
+`ready_for_image_generation`.
+
+## Dailin Workflow Mapping
+
+This file is the OW-owned equivalent of dailin
+`vision_to_strategic_prototype_prompt/reference/06_quality_rubric.md`.
+It maps dailin's final quality check into OW's readiness gate for prompt text.
+
+The dailin `OUTPUT_PROMPT.md` examples are the minimum passing benchmark for
+paragraph density and generation usefulness. Passing means the prompt text is a
+complete high-fidelity prototype-generation brief, not merely a valid YAML
+record with present fields.
+
+The senior product-manager perspective is also part of readiness. Passing
+prompt text must show judgment: a product thesis, reason-to-exist,
+differentiated product form, target user transformation, and design philosophy.
+References and schema fields are tools, not proof that the prompt has taste or
+strategic force.
+
+## Perspective And Product Judgment
+
+Verify:
+
+- Each direction has a product thesis, not just a screen list.
+- Each direction names the target user transformation it is trying to make
+  visible.
+- Each direction explains why its product form deserves to exist now.
+- The prompt avoids reflexively choosing a dashboard, chatbot, card wall,
+  report screen, or SaaS shell unless that form is strategically justified.
+- `pm_judgment` states what assumption the direction tests, what risk it
+  exposes, and why it should be generated first or later.
+- The design philosophy is legible in the prompt: what the product should feel
+  like, what it refuses to become, and what user control it protects.
+
+## Strategic Differentiation
+
+Verify:
+
+- Each direction has a distinct strategic hypothesis.
+- Each direction has a distinct product thesis or product-form point of view.
+- Each direction changes product form, trigger, interaction model, emotional
+  driver, retention mechanism, validation metric, trust model, privacy model,
+  or main risk.
+- Directions are not visual style variants.
+- Scenario labels are not mistaken for strategic directions.
+- The selected directions cover the most important uncertainty space.
+
+## Vision Alignment
+
+Verify:
+
+- Target user from the vision is preserved.
+- Desired behavior change is explicit.
+- Strongest success signal is explicit.
+- Core differentiator appears in every direction.
+- Future opportunities are not treated as first-version requirements.
+- Non-goals become anti-goals in prompt text.
+- Trust/privacy requirements appear as UI or interaction controls.
+
+## Prompt Executability
+
+Verify:
+
+- Product name is included.
+- Product positioning is clear.
+- Target user is concrete.
+- Core product idea is stated.
+- Required screens are listed.
+- Every screen has concrete UI requirements.
+- Every screen has meaningful state or an explicit reason it does not need one.
+- Required data fields and example copy are present.
+- Primary actions and system responses are present.
+- AI/system behavior is specified when relevant.
+- Negative prompts and anti-goals are explicit.
+- Desired user feeling is clear.
+- Acceptance criteria are screen-bound and checkable.
+- Direction-level `prototype_prompt` text includes product context, target
+  user, journey, screens, interactions, system response, trust controls,
+  visual direction, anti-goals, desired user feeling, product thesis,
+  reason-to-exist, and user transformation.
+- Screen-level `screen_prompts[].prompt` text is standalone enough to generate
+  the screen and includes purpose, components, state, concrete data or copy,
+  actions, system response, trust controls, negative constraints, and
+  acceptance criteria.
+
+## Product Specificity
+
+Verify:
+
+- `product_experience_model` names the product archetype and primary canvas.
+- The artifact names domain objects, not just generic UI components.
+- The screen_manifest includes selected objects, states, or workflow stages
+  when the product category requires them.
+- The prompt contains realistic fields, values, labels, owners, timestamps,
+  copy, or metrics.
+
+## Trust And Safety
+
+Verify:
+
+- No manipulative guilt language.
+- No fake human identity unless explicitly safe and required.
+- No intrusive intimacy or overattachment mechanics.
+- No empty praise as the main feedback mechanism.
+- No overpromising real-world outcomes.
+- User controls are visible where memory, personalization, automation, or
+  sensitive data are involved.
+- Sensitive data defaults are conservative.
+- Autonomous action is blocked when human approval is required.
+
+## Integrity And Readiness
+
+Verify:
+
+- `prompt_pack_integrity_gate.status` is `pass`.
+- `prototype_reality_gate.status` is `pass`.
+- `quality_rubric.prompt_paragraph_quality.status` is `pass` or equivalent
+  prompt paragraph quality evidence is present.
+- `prompt_text_manifest.paragraph_quality_status` is `pass`.
+- `prompt_text_manifest.paragraph_quality_dimensions` records the checked
+  dimensions for product context, target user, journey, screens/components,
+  interaction or system response, concrete content, trust or user control,
+  visual direction, anti-goals, desired user feeling, and perspective engine.
+- `post_validate.status` is `pass` for multi-direction packs or `skipped` for
+  explicit single-direction packs.
+- `prompt_text_manifest.direction_count` equals `directions.length`.
+- `prompt_text_manifest.prompt_text_refs` resolve to source directions or
+  screen prompts.
+- `image_generation.status` is `not_started` until all gates pass.
+
+## Common Failure Modes
+
+- Strategy collapsed into UI style.
+- Structural completeness without product judgment.
+- Persona language such as "senior PM" appears, but the prompt still lacks a
+  product thesis, user transformation, or reason-to-exist.
+- Prompt is too abstract for a design tool.
+- Prompt is a short screen-state instruction instead of a full
+  prototype-generation brief.
+- Vision non-goals are ignored.
+- AI behavior is unspecified.
+- Trust controls are described in prose but absent from UI.
+- Markdown prompt is richer than YAML source.
+- EVIDENCE references prompts that do not exist in the prompt pack.
+
+## Thin Prompt Failures
+
+Fail prompt readiness even when YAML fields are present if any prompt paragraph
+looks like these patterns:
+
+```text
+Show the dashboard with the approval drawer open.
+```
+
+```text
+Create a modern AI assistant screen for incident response.
+```
+
+```text
+Design a beautiful analytics page with charts and recommendations.
+```
+
+These prompts fail because they omit the strategic context, target user,
+journey stage, concrete domain objects, user action, system response,
+trust/control behavior, anti-goals, and desired user feeling needed for
+dailin-grade image generation.
+
+Revise before final if any required check fails.

package/skills/build-validation/SKILL.md

@@ -1,81 +1,163 @@
 ---
 name: build-validation
-description: Create validation-first prioritization artifacts from a product vision or change idea. Use when the user asks what should be prioritized, what must be proven first, which feature is core versus supporting, or when a broad idea needs a prototype brief before /ow:change, /ow:team, or implementation work.
+description: Compile a proto-ready vision into one prototype validation target. Use when the user invokes /ow:validation, asks what the prototype must prove first, or needs to turn product intent into an experiment brief before /ow:proto.
 ---
 
 # Build Validation
 
 ## Purpose
 
-Identify the smallest proof needed to make a vision credible before converting
-it into implementation scope. This skill ranks assumptions, not backlog tasks.
+Turn proto-ready vision into a single prototype validation target.
 
-It answers:
+This skill is the native source behavior for `/ow:validation`. It is not a
+feature ranking helper, backlog planner, or prototype generator. It exists
+between `/ow:vision` and `/ow:proto` to decide what the next prototype must
+prove before prototype prompts are written.
 
-- Which feature is existential to the vision?
-- Which features support the core experience?
-- Which features are later, operational, or out of scope for validation?
-- What is the smallest prototype that can prove or disprove the core assumption?
-- What evidence decides whether to continue, pivot, stop, or gather more data?
+`build-validation` acts as:
+
+- assumption auditor
+- experiment designer
+- prototype target compiler
+
+It should protect `/ow:proto` from generating attractive prototype directions
+that do not reduce the most important product uncertainty.
 
 ## Inputs
 
-Read only the relevant upstream contracts:
+Required:
+
+- `.openworkflow/vision/VISION_CONTRACT.yaml`
+- `.openworkflow/vision/VISION.md` or the active vision session summary
+
+Optional:
+
+- `.openworkflow/context/CONTEXT.md`
+- `.openworkflow/context/CONTEXT_MAP.yaml`
+- `.openworkflow/context/GLOSSARY.yaml`
+- `.openworkflow/validation/VALIDATION_INDEX.yaml`
+- `skills/build-validation/references/prototype-validation-target-rubric.md`
+- `skills/build-validation/references/return-to-vision-gate.md`
+
+Avoid loading prototype, spec, change, runtime, or implementation artifacts
+unless the user explicitly asks to reconcile with historical evidence.
+
+## Core Job
+
+Given a vision, answer:
+
+- What is the central uncertainty that the next prototype must reduce?
+- What user behavior would make the product thesis more credible?
+- What prototype scene, journey, or interaction must be shown to observe that
+  behavior?
+- What evidence would count as pass, revise, pivot, stop, or needs_more_evidence?
+- What vision gaps make a valid validation target impossible?
+
+If those answers are not available, return to `/ow:vision` instead of forcing a
+weak validation target.
+
+## Vision Readiness Gate
 
-- `.codex/workflow/WORKFLOW_INDEX.yaml`
-- `.codex/workflow/CONTRACT_GRAPH.yaml`
-- `.codex/context/CONTEXT_MAP.yaml` when present and relevant
-- `.codex/vision/VISION_CONTRACT.yaml` or the user's product vision
-- `.codex/decisions/DECISION_INDEX.yaml` when decisions constrain the prototype
-- `.codex/spec/SPEC_INDEX.yaml` only for directly relevant binding constraints
+Before writing validation artifacts, check that vision provides enough evidence
+for:
 
-Avoid loading archives, unrelated specs, reviews, or runtime state unless the
-user asks for historical evidence.
+- target user
+- usage context
+- current alternative
+- desired behavior change
+- core mechanism
+- differentiator
+- trust, privacy, safety, and user-control boundaries
+- strongest success signal
+- failure signals
+- prototype direction seeds
+- prompt constraints
 
-## Output
+When the missing information would cause `/ow:proto` to invent product strategy,
+record the gap and hand back to `/ow:vision`.
 
-Write validation artifacts under:
+## Output Contract
 
-```txt
-.codex/validation/<validation_id>/
-  VALIDATION.yaml
-  PROTOTYPE_BRIEF.md
-  RESULT.md
-  archive/
+Write validation artifacts only when the target is coherent:
+
+```text
+.openworkflow/validation/VALIDATION_INDEX.yaml
+.openworkflow/validation/<id>/VALIDATION.yaml
+.openworkflow/validation/<id>/NOTE.md
+```
+
+The validation target should preserve:
+
+```yaml
+core_question:
+central_uncertainty:
+hypothesis:
+target_behavior:
+prototype_scope:
+  include:
+  exclude:
+prototype_experiment:
+  scenario:
+  must_show:
+  must_not_show:
+observable_signals:
+  pass:
+  fail:
+  ambiguous:
+decision_rules:
+  continue:
+  revise:
+  pivot:
+  stop:
+  needs_more_evidence:
+vision_gaps:
 ```
 
-`RESULT.md` may remain a placeholder until a prototype is tested.
+Until the artifact schema formally exposes every field, keep the same
+information in the existing `core_question`, `critical_assumptions`,
+`prototype_scope`, `acceptance`, and `NOTE.md` fields without losing the
+experiment logic.
 
 ## Workflow
 
-1. Restate the vision in one sentence.
-2. Build a feature landscape:
-   - `existential`: without this, the vision does not hold
-   - `supporting`: makes the core feature useful
-   - `later`: valuable after the core assumption is proven
-   - `out_of_scope`: explicitly excluded from validation
-3. Identify critical assumptions and rank the riskiest first.
-4. Define one minimum prototype scope.
-5. Define acceptance as evidence questions, not implementation completeness.
-6. Initialize artifacts with `scripts/init_validation.py`.
-7. Validate with `npm run validate` when the repository validator exists.
-
-## Boundaries
-
-- Do not create full implementation tasks.
-- Do not write large product specs.
-- Do not solve authentication, persistence, deployment, billing, or admin work
-  unless those are the existential assumption.
-- Do not treat feature count as progress.
-- Prefer a small prototype brief over a broad spec when uncertainty is high.
+1. Load current vision and current validation index, if any.
+2. Extract the candidate uncertainties from the vision.
+3. Rank uncertainties by existential risk, observability in prototype,
+   decision leverage, and cost of learning.
+4. Select exactly one central uncertainty for the next validation target.
+5. Define one minimum prototype experiment.
+6. Convert success and failure signals into observable evidence criteria.
+7. Define decision rules for continue, revise, pivot, stop, and
+   needs_more_evidence.
+8. Write validation artifacts only after the target is coherent.
 
-## Handoff
+## Prototype Handoff
+
+`/ow:proto` should be able to consume the validation target as an experiment
+brief. It should not need to infer:
 
-If validation is planned, hand off to `/ow:prototype` or an implementation
-agent with the prototype brief only.
+- which uncertainty matters most
+- which screen or journey moments are required
+- which user behavior is being observed
+- which anti-goals and trust boundaries constrain the prototype
+- what evidence changes the next decision
+
+When validation is present, `/ow:proto` should treat it as the target of the
+prototype prompt pack.
+
+## Forbidden Defaults
+
+- Do not generate prototype prompts.
+- Do not create prototype images or prototype evidence.
+- Do not produce production specs, changes, tasks, or implementation plans.
+- Do not turn supporting features into blockers for the central uncertainty.
+- Do not select multiple unrelated validation targets in one artifact.
+- Do not hide vision gaps by writing a polished but unsupported target.
+
+## Handoff
 
-If validation passes, feed `VALIDATION.yaml` and `RESULT.md` into
-`/ow:decision`, `/ow:spec`, or `/ow:change`.
+Hand off to `/ow:proto` only when the validation target names a central
+uncertainty, prototype scope, observable evidence, and decision rules.
 
-If validation fails, revise the vision or create a new validation contract
-before generating implementation tasks.
+Hand back to `/ow:vision` when the target would require inventing product
+strategy.

package/skills/build-validation/references/prototype-validation-target-rubric.md

@@ -0,0 +1,35 @@
+# Prototype Validation Target Rubric
+
+A validation target is useful only if it helps `/ow:proto` design an experiment,
+not just a polished interface.
+
+## Required Qualities
+
+- Central uncertainty: one uncertainty that would materially change the product
+  direction if disproven.
+- Target behavior: the user behavior or reaction the prototype must make
+  observable.
+- Prototype boundary: the minimum scene, journey, states, and interactions that
+  must be shown.
+- Evidence criteria: pass, fail, and ambiguous signals expressed as observable
+  prototype review evidence.
+- Decision rules: how evidence maps to continue, revise, pivot, stop, or
+  needs_more_evidence.
+
+## Rejection Signs
+
+- The target is a list of features.
+- The target can be satisfied by making the UI attractive.
+- The target needs production infrastructure to be meaningful.
+- The target asks the prototype to prove several unrelated assumptions.
+- The target omits what would count as failure.
+- The target requires `/ow:proto` to invent product strategy.
+
+## Strong Target Shape
+
+```text
+We need to learn whether [target user], in [context], would [target behavior]
+because [core mechanism] solves [pain] better than [current alternative].
+The prototype must show [must-show moments] and must avoid [anti-goals].
+Pass if [observable signal]. Fail if [observable signal].
+```

package/skills/build-validation/references/return-to-vision-gate.md

@@ -0,0 +1,32 @@
+# Return-To-Vision Gate
+
+Validation should not compensate for weak vision. It should identify when the
+next useful action is more vision discovery.
+
+Return to `/ow:vision` when any of these are missing or conflicted:
+
+- target user
+- usage context
+- desired behavior change
+- core mechanism
+- differentiator
+- trust or privacy boundary
+- strongest success signal
+- failure signal
+- prototype direction seed
+- prompt constraint
+
+## Agent Rule
+
+If the missing information would force `/ow:proto` to invent strategy, stop
+validation and ask the next vision question instead of writing a validation
+target.
+
+## Partial Validation Exception
+
+A partial validation target is acceptable only when:
+
+- the missing vision area is explicitly named in `vision_gaps`
+- the prototype can still observe one central uncertainty without inventing the
+  missing strategy
+- the user understands the validation target is intentionally partial

package/skills/build-vision/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: build-vision
+description: Conduct deep product vision discovery without eager artifact writes, then compile proto-ready vision artifacts only after the user confirms readiness. Use when the user invokes /ow:vision, wants to clarify a product idea, or needs a vision that can drive high-quality prototype prompts.
+---
+
+# Build Vision
+
+## Purpose
+
+Turn messy product intent into a proto-ready vision contract.
+
+This skill is the native source behavior for `/ow:vision`. It treats vision as
+the highest-leverage discovery stage because every downstream artifact depends
+on it. If the vision is thin or wrong, validation, prototype prompts, generated
+prototypes, tuning, specs, and implementation all become expensive work against
+weak intent.
+
+`build-vision` acts as:
+
+- product partner
+- requirements interrogator
+- intent compiler
+
+It should make the human interview feel fluid while still producing durable,
+auditable artifacts at meaningful checkpoints.
+
+## Inputs
+
+Required, one of:
+
+- direct user product idea, opportunity, or broad goal
+- existing `.openworkflow/vision/VISION_CONTRACT.yaml`
+- existing `.openworkflow/vision/VISION.md`
+- existing `.openworkflow/vision/sessions/<id>/VISION_SESSION.yaml`
+
+Optional:
+
+- `.openworkflow/CURRENT_STATE.yaml`
+- `.openworkflow/context/CONTEXT.md`
+- `.openworkflow/context/CONTEXT_MAP.yaml`
+- `.openworkflow/context/GLOSSARY.yaml`
+- `docs/DISCOVER_LOOP_UPGRATE_PLAN.md`
+- `skills/build-vision/references/vision-interview-protocol.md`
+- `skills/build-vision/references/proto-readiness-rubric.md`
+- reference product notes, constraints, screenshots, or prior discovery notes
+
+Avoid loading validation, prototype, spec, change, runtime, or implementation
+history unless the user's current vision question explicitly depends on it.
+
+## Interaction Modes
+
+### Interview Mode
+
+Default mode. Ask one focused question at a time and do not write durable
+`.openworkflow/vision/**` artifacts after every answer.
+
+Use conversation context as temporary working memory. Preserve flow, challenge
+weak answers, and keep exploring until the product intent is strong enough to
+compile.
+
+### Checkpoint Mode
+
+Write a lightweight checkpoint only when:
+
+- the user explicitly asks to record progress
+- a topic closes
+- the user needs to pause
+- the session contains a load-bearing ambiguity that should not be lost
+- a long interview reaches a natural review point
+
+Checkpoint mode is not final vision compile.
+
+### Compile Mode
+
+Compile durable artifacts only when:
+
+- mandatory discovery dimensions have enough evidence
+- proto-readiness is sufficient
+- unresolved blockers are explicit
+- the user confirms that the interview can stop
+
+Expected durable outputs:
+
+```text
+.openworkflow/vision/VISION.md
+.openworkflow/vision/VISION_CONTRACT.yaml
+.openworkflow/vision/sessions/<id>/VISION_SESSION.yaml
+.openworkflow/vision/sessions/<id>/NOTE.md
+```
+
+Context files may be updated only when context has stabilized.
+
+## Discovery Coverage
+
+Before compile, cover:
+
+- target user and beneficiary
+- usage context
+- current alternative
+- pain and motivation
+- desired behavior change
+- core product mechanism
+- core differentiator
+- emotional value
+- functional value
+- strongest success signal
+- failure signals
+- trust, privacy, safety, and user-control boundaries
+- explicit non-goals
+- future opportunities that must remain deferred
+- validation target
+
+Do not treat this as a fixed questionnaire. Follow the user's answers and
+continue deeper when an answer exposes ambiguity, contradiction, or leverage.
+
+## Proto-Readiness Gate
+
+`VISION.md` is ready only when `/ow:proto` can use it to generate high-quality
+strategic prototype prompt packs without inventing the core product strategy.
+
+Before compile, verify that `/ow:proto` could derive:
+
+- 3-5 strategically distinct prototype directions
+- target user, behavior change, mechanism, differentiator, and boundary
+  conditions
+- complete screen and journey requirements
+- AI/system behavior when AI is part of the product
+- trust, privacy, safety, and user-control constraints
+- anti-goals converted into prompt constraints
+- strongest success and failure signals
+- a clear validation target
+
+If these cannot be derived, continue interviewing or record explicit blockers.
+
+## Artifact Guidance
+
+When compiling, preserve:
+
+```yaml
+strategic_core:
+  target_user:
+  context:
+  current_alternative:
+  pain:
+  desired_behavior_change:
+  core_mechanism:
+  core_differentiator:
+  strongest_success_signal:
+  failure_signals:
+
+product_system_seed:
+  product_thesis:
+  primary_loop:
+  interaction_model:
+  feature_system:
+  emotional_value:
+  functional_value:
+  trust_boundary:
+  privacy_boundary:
+  anti_goals:
+  future_opportunities:
+
+proto_readiness:
+  status: missing|thin|ready|blocked
+  missing_for_proto:
+  prototype_direction_seeds:
+  prompt_constraints:
+  validation_target:
+  downstream_notes:
+```
+
+Use coverage statuses such as `missing`, `thin`, `solid`, and `conflicted` when
+a dimension is not ready.
+
+## Forbidden Defaults
+
+- Do not write durable vision files after every user answer.
+- Do not compile final vision artifacts after a fixed small number of questions.
+- Do not create validation, prototype, spec, change, or runtime artifacts.
+- Do not create prototype prompts from `/ow:vision`; hand off to `/ow:proto`.
+- Do not hide thin or conflicted answers as polished product truth.
+- Do not preserve auditability by destroying conversation flow.
+
+## Handoff
+
+Hand off to `/ow:validation` only after compile mode has produced proto-ready
+vision artifacts or after the user explicitly asks for validation against a
+known partial vision.
+
+If the user asks for prototype prompts directly, first check proto-readiness.
+When ready, hand off to `/ow:proto`; when thin, continue the vision interview.
+