@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/skills/decompose-to-changes/references/decomposition-protocol.md

@@ -0,0 +1,278 @@
+# Decomposition Protocol
+
+Use this reference when turning planning input into `CANDIDATE_CHANGES.yaml`,
+`CANDIDATE_CHANGES.md`, and `SUMMARY.yaml`.
+
+## Input Normalization
+
+Capture the source as one of:
+
+- `user_input`: direct instruction or pasted plan
+- `planning_discussion`: latest session discussion
+- `artifact`: named repo files such as `VISION.md` or `OW_DEVELOP_PLAN.md`
+- `mixed`: a small set of explicit files plus session discussion
+
+Prefer a narrow source set. Do not load archives, generated runtime state, or
+unrelated implementation history unless the user names them.
+
+## Candidate Shape
+
+Each candidate should answer:
+
+- What one outcome changes?
+- Which paths own that outcome?
+- What is explicitly out of scope?
+- What must happen first?
+- What downstream work does it unlock?
+- How will an implementer verify it?
+- What acceptance facts prove it is done?
+
+Good candidates are small enough for one focused implementation pass. A
+candidate is too broad when it owns multiple unrelated modules, mixes source
+skill authoring with runtime command exposure, or requires both product design
+and production implementation.
+
+## Queue Scope Control
+
+Before creating or maintaining candidates, decide the queue boundary separately
+from the source discussion. The source may contain a full product vision,
+multi-stage roadmap, or several future features; the queue must still remain a
+reasonable development scope.
+
+A valid queue usually covers exactly one of:
+
+- one feature outcome
+- one bounded module
+- one command surface
+- one artifact family
+- one workflow slice
+
+A queue is too broad when it contains multiple independent features, a large
+module family, or candidates that would naturally require separate milestone
+branches. In that case, choose the smallest current feature boundary that can
+move development forward and record the rest outside the active `changes` list.
+
+Use top-level `scope_control` for this decision:
+
+```yaml
+scope_control:
+  current_boundary: Workflow command taxonomy and stage graph only.
+  boundary_type: workflow_slice
+  in_scope_rule: Include only candidates needed to complete this boundary.
+  out_of_scope_rule: Record later features as deferred refs; do not include them as current candidates.
+  deferred_features:
+    - title: proto2html runtime contract
+      reason: Separate command surface; needs its own DTC pass after taxonomy.
+      suggested_plan_id: M74-proto2html-runtime-contract
+```
+
+`deferred_features` are not candidates and must not be referenced as
+dependencies or unlocks. They are planning memory for future DTC passes. When a
+deferred feature becomes active, create a new `CANDIDATE_CHANGES.yaml` queue
+for that feature and cite the original queue as source evidence.
+
+## Feat And Commit Cadence
+
+The queue is the feat. `changes/<plan_id>/CANDIDATE_CHANGES.yaml` defines the
+feature-sized planning boundary and should remain the durable source of truth
+until that feature is complete or superseded.
+
+Individual candidates are commit-sized changes inside the current feat. Do not
+create sibling top-level folders such as `changes/<new-id>/` for every
+candidate. Selection artifacts should live under the current feat folder, for
+example:
+
+```text
+changes/<plan_id>/
+  CANDIDATE_CHANGES.yaml
+  CANDIDATE_CHANGES.md
+  SUMMARY.yaml
+  <candidate-id>-<slug>/
+    SELECTED_CHANGE.yaml
+    ATOM_TASKS.yaml
+    IMPLEMENTATION_BRIEF.md
+```
+
+Open a new top-level feat folder only when a new decomposition queue is needed.
+Otherwise, update the existing queue by candidate id and let each completed
+candidate land as a normal git commit.
+
+## Branch Boundary
+
+When creating a new queue, capture the branch context from
+`git status --short --branch`.
+
+Record the intended feat branch under:
+
+```yaml
+queue_policy:
+  branch_boundary: codex/<feat-branch>
+```
+
+Use the current branch when it already matches the new feat. If branch creation
+has not happened yet, record the proposed branch name and note the gap in
+`SUMMARY.yaml`. Do not create or switch branches as part of this skill.
+
+When maintaining an existing queue, preserve `queue_policy.branch_boundary`.
+If the current branch differs from the recorded boundary, add an operation or
+summary note explaining why maintenance is still valid.
+
+## Status Guidance
+
+Use these statuses:
+
+- `ready`: dependencies are satisfied and the candidate can be selected.
+- `candidate`: valid but blocked by incomplete dependencies or sequencing.
+- `blocked`: cannot be clarified or implemented without an explicit decision.
+- `deferred`: useful but intentionally postponed.
+- `superseded`: replaced by a newer candidate; keep evidence.
+
+When updating an existing queue, never renumber stable ids. If a candidate
+changes meaningfully, add a note or create a new candidate rather than reusing
+the old id for a different scope.
+
+## Queue Maintenance Operations
+
+Use queue maintenance when the user asks to inspect or surgically change an
+existing `CANDIDATE_CHANGES.yaml`.
+
+Supported operations:
+
+- `query`: answer by candidate id, status, dependency, owned path, risk, or
+  readiness.
+- `add`: append a new candidate with a fresh stable id.
+- `update`: change fields while preserving candidate identity.
+- `status_change`: move between `candidate`, `ready`, `blocked`, `deferred`,
+  `superseded`, `selected`, `in_progress`, or `done`.
+- `split`: replace one broad candidate with multiple narrower candidates.
+- `merge`: combine overlapping candidates by keeping one survivor and marking
+  the others `superseded`.
+- `priority_change`: update `next_recommended_candidate_id` or ready ordering.
+
+Each mutating operation should append an item under top-level `operations`:
+
+```yaml
+operations:
+  - operation_id: OP001
+    operation_type: update
+    target_candidate_ids:
+      - C002
+    actor: agent
+    reason: Clarify owned paths before selection.
+    changed_at: 2026-05-21
+    before_status: candidate
+    after_status: ready
+    evidence:
+      - changes/<id>/...
+```
+
+Use sequential operation ids such as `OP001`, `OP002`, `OP003`. If the queue
+already has operations, continue the sequence.
+
+Do not hard-delete historical candidates. Prefer `superseded`, `deferred`, or
+`blocked`. Hard deletion is only acceptable for a malformed candidate created in
+the same uncommitted operation; log the reason.
+
+## High-Risk Decision Reports
+
+Use `HIGH_RISK_DECISION_REPORT.md` when queue maintenance discovers that the
+next work is high risk and needs user confirmation before implementation. This
+is especially important for adapter delivery, generated runtime surfaces,
+security, data handling, trust model, or broad architecture changes.
+
+Report creation is a queue maintenance action. It does not select the high-risk
+candidate and does not authorize implementation.
+
+When creating or updating the report:
+
+1. Keep the high-risk candidate id stable.
+2. Preserve the candidate status unless the user explicitly asks to mark it
+   `blocked`, `deferred`, or `superseded`.
+3. Write or update `changes/<plan_id>/HIGH_RISK_DECISION_REPORT.md`.
+4. Add the report path to `SUMMARY.yaml` outputs or notes.
+5. Refresh `CANDIDATE_CHANGES.md` with the report path when useful.
+6. Append an operation entry:
+
+```yaml
+operations:
+  - operation_id: OP012
+    operation_type: query
+    target_candidate_ids:
+      - C007
+    actor: agent
+    reason: High-risk stop converted into a decision report before implementation.
+    changed_at: 2026-05-21
+    before_status: candidate
+    after_status: candidate
+    evidence:
+      - changes/<plan_id>/HIGH_RISK_DECISION_REPORT.md
+```
+
+Use `operation_type: block` only when the queue status or candidate status is
+also changed to `blocked`. Use `query` when the report is informational and the
+candidate remains in its current status.
+
+Required report sections are defined in
+`references/planning-artifact-contracts.md`.
+
+Do not create multiple reports for the same risk boundary. Update the existing
+report unless the new high-risk stop concerns a materially different decision.
+
+## Output Checklist
+
+`CANDIDATE_CHANGES.yaml` must include:
+
+- `schema_version: 0.1.0`
+- `contract_id: candidate_changes:<plan_id>`
+- `contract_type: planning`
+- `planning_artifact_type: candidate_changes`
+- `plan_id`
+- `title`
+- `status`
+- `source`
+- `queue_policy`
+- `selection_policy`
+- `scope_control` when the source discussion spans more than one feature,
+  command surface, artifact family, module, or workflow slice
+- `queue_policy.branch_boundary` for new branch-governed queues
+- `next_recommended_candidate_id` when appropriate
+- `changes`
+- `operations` when the queue has been maintained after initial creation
+
+`CANDIDATE_CHANGES.md` should include:
+
+- source-of-truth notice
+- selection policy summary
+- branch boundary when present
+- next recommended candidate when present
+- one compact section per candidate
+
+`SUMMARY.yaml` should include:
+
+- source summary
+- scope boundary summary and deferred feature refs when present
+- output paths
+- branch boundary when present
+- candidate count
+- next recommended candidate
+- unresolved questions
+- validation commands run
+
+## Review Before Finishing
+
+Check that:
+
+- every candidate has focused `owned_paths`
+- the queue itself covers one feature, bounded module, command surface, artifact
+  family, or workflow slice
+- later or adjacent features are captured as deferred refs, not current
+  candidates
+- includes and excludes are both present
+- dependencies reference stable candidate ids
+- validation commands are realistic for this repo
+- no candidate silently starts implementation
+- generated or runtime paths are protected unless explicitly in scope
+- every mutating maintenance edit has an operation log entry
+- every status change preserves or adds evidence
+- high-risk candidates that require confirmation have a linked report before
+  implementation resumes

package/skills/prompt2proto/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: prompt2proto
+description: Translate ready PROTO_PROMPT_PACK artifacts into credible UI/UX prototype instructions, evidence plans, and downstream handoff records. Use after vision2prompt/build-proto-prompt has produced ready prompt text and before provider-backed image generation, visual review, proto2html, specs, changes, or runtime work.
+---
+
+# Prompt2Proto
+
+## Purpose
+
+Translate ready strategic prototype prompt packs into reviewable UI/UX
+prototype instructions and evidence records. This skill is the source method
+behind the internal `/ow:prompt2proto` stage, but it does not by itself call an
+image provider or claim visual quality.
+
+`prompt2proto` starts where build-proto-prompt or its compatible vision2prompt
+compiler path ends. It consumes a ready `PROTO_PROMPT_PACK`, preserves the
+product strategy and screen coherence contracts, and turns them into a concrete
+prototype translation plan that build-prototype can use without inventing
+product intent.
+
+## Role Engine
+
+Before translating, load
+`skills/prompt2proto/references/00_role_philosophy_engine.md`.
+
+Operate as:
+
+- Chief PM: protects product intent, user decision context, workflow priority,
+  domain fit, and evidence value.
+- Principal UI/UX / product design lead: protects visual hierarchy,
+  information density, layout anatomy, affordance clarity, interaction
+  believability, and prototype inspection quality.
+
+The role engine is required. A structurally complete translation still fails if
+it reads like a generic image prompt, a decorative dashboard, a card wall, or a
+concept poster rather than a plausible product interface.
+
+Use this role engine as the build-prototype philosophy engine: Chief PM plus
+Principal UI/UX judgment must come before visual translation. The Chief PM
+decides product intent, domain fit, user decision context, and evidence value;
+the Principal UI/UX lead decides information hierarchy, density calibration,
+affordance clarity, interaction believability, and UI/UX credibility.
+
+## Inputs
+
+Required:
+
+- `.openworkflow/prototypes/<id>/PROTO_PROMPT_PACK.yaml` or an equivalent
+  ready prompt pack artifact
+- prompt text with `prompt_text_manifest.status: ready_for_image_generation`
+- `prompt_text_manifest.paragraph_quality_status: pass`
+- `prompt_pack_integrity_gate.status: pass`
+- `prototype_reality_gate.status: pass`
+- `quality_rubric.prompt_executability.status: pass`
+- `post_validate.status: pass` for multi-direction packs, or `skipped` for an
+  explicit single-direction pack
+
+Optional:
+
+- `PROTO_PROMPT_PACK.md` readable view
+- `EVIDENCE.yaml` or `EVIDENCE.md` for existing prototype lineage
+- selected direction constraints from user review
+- target medium, provider, canvas, viewport, or image count constraints
+
+## References
+
+Run these references in order:
+
+1. `references/00_role_philosophy_engine.md`: role, taste, and guardrails.
+2. `references/01_input_contract.md`: input readiness and refusal policy.
+3. `references/02_prompt_pack_readiness.md`: gate and coherence checks.
+4. `references/03_visual_translation_workflow.md`: UI/UX translation method.
+5. `references/04_output_contract.md`: output and metadata shape.
+6. `references/05_quality_rubric.md`: final review before handoff.
+
+Load only the reference needed for the current step.
+
+## Output
+
+For source-level dogfood, write evidence under the selected change folder. For
+workflow execution, write under the active prototype folder selected by the
+command.
+
+Expected output families:
+
+```text
+PROMPT2PROTO_TRANSLATION_PLAN.md
+PROMPT2PROTO_EVIDENCE.yaml
+NOTE.md
+```
+
+When a provider-backed generation stage is explicitly authorized later, the
+same contract can support image metadata records. This skill only defines the
+translation and evidence contract; it does not start provider generation.
+
+## Workflow
+
+1. Load the role engine and required input contract.
+2. Refuse missing, thin, stale, incoherent, or not-ready prompt packs.
+3. Preserve strategy from the prompt pack: product thesis, target user,
+   user transformation, primary loop, trust boundaries, non-goals, and
+   direction-level reasons to exist.
+4. Preserve technical screen coherence from the prompt pack: app shell,
+   navigation taxonomy, domain objects, screen ids, state model, data
+   vocabulary, and allowed screen-specific deltas.
+5. Apply the philosophy engine before translating screens: decide what must be
+   visible, grouped, collapsed, delayed, or drilled into based on industry,
+   role, risk, screen size, task frequency, and the user's next decision.
+6. Translate each selected direction into a prototype system plan: screen
+   sequence, hierarchy, density, component anatomy, state behavior,
+   interaction affordances, sample data, trust controls, and negative visual
+   constraints.
+7. Calibrate information density as design judgment, not prompt length:
+   decide what is visible, grouped, collapsed, delayed, or drilled into based
+   on industry, role, risk, screen size, task frequency, and user attention.
+8. Write translation evidence that names accepted inputs, refusals, output
+   refs, limitations, and the next authorized handoff.
+9. Stop before provider-backed generation, human visual review, visual parity,
+   proto2html, storyboard, motion, specs, changes, or runtime work unless a
+   later selected candidate explicitly authorizes that surface.
+
+## Build-Prototype Consumption Boundary
+
+`build-prototype` consumes prompt2proto; it must not re-run vision-to-prompt
+compilation, invent strategic directions, or repair prompt paragraphs. When a
+prompt pack is not ready, route repair back to `/ow:build-proto-prompt` or the
+compatible `/ow:vision2prompt` compiler path and keep image generation or
+visual acceptance evidence out of scope.
+
+## Refusal Rules
+
+Refuse and route back to prompt-pack repair when:
+
+- readiness gates are missing or failing;
+- prompt paragraphs are not dailin-grade or omit journey, interaction
+  behavior, system response, trust controls, anti-goals, visual direction,
+  desired user feeling, or concrete content;
+- screen prompts do not resolve to `screen_manifest.target_screen_id`;
+- screen coherence contracts are missing when multiple screens must share one
+  product shell;
+- the prompt pack asks prompt2proto to invent strategy instead of translate
+  ready strategy;
+- the requested output is provider generation, human visual review, visual
+  parity scoring, proto2html, storyboard, motion, spec, change, or runtime
+  work.
+
+## Handoff
+
+When translation passes, hand back to the orchestrating prototype workflow with
+clear next actions:
+
+- generate provider images only when a later queue authorizes it;
+- repair prompt pack through build-proto-prompt/vision2prompt when readiness
+  fails;
+- move to tune only after accepted visual evidence exists;
+- move to proto2html only after an accepted benchmark image or screen group
+  exists.

package/skills/prompt2proto/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Prompt2Proto"
+  short_description: "Translate ready prompt packs into UI/UX prototype instructions"
+  default_prompt: "Use prompt2proto to consume a ready PROTO_PROMPT_PACK and produce credible UI/UX prototype translation instructions and evidence without starting provider generation."

package/skills/prompt2proto/references/00_role_philosophy_engine.md

@@ -0,0 +1,96 @@
+# 00 Role And Philosophy Engine
+
+Use this reference before any prompt2proto translation.
+
+## Identity
+
+Act as a combined Chief PM and Principal UI/UX product design lead.
+
+The Chief PM protects why the prototype exists: target user, product thesis,
+behavior change, validation risk, business/domain fit, and evidence value.
+
+The Principal UI/UX lead protects how the prototype becomes credible:
+information architecture, visual hierarchy, density, screen anatomy, component
+behavior, interaction affordances, and inspection quality.
+
+## Perspective Lens
+
+Notice:
+
+- whether the prompt pack already contains strategy or is asking this stage to
+  invent it;
+- whether screen groups share a stable product shell and data vocabulary;
+- whether the main canvas matches the product category;
+- whether density matches user role, task risk, screen size, and frequency;
+- whether trust, safety, privacy, and approval controls are visible in UI, not
+  only prose;
+- whether sample data, labels, owners, timestamps, and states feel like real
+  operational work.
+
+Decide before translation:
+
+- what is visible because it changes the next decision;
+- what is grouped because related fields must be compared;
+- what is collapsed because it is secondary but still inspectable;
+- what is delayed until the user expresses intent;
+- what becomes drill-down detail because it would overload the main canvas.
+
+Prioritize:
+
+- product credibility over decorative novelty;
+- inspectable screen anatomy over vague mood-board language;
+- visible user control over magical automation;
+- coherent multi-screen systems over isolated screenshots;
+- concrete content and state behavior over generic components.
+
+Reject:
+
+- generic dashboards, card walls, chatbot shells, consulting report screens,
+  or SaaS templates when the prompt pack calls for a more specific product
+  form;
+- concept posters that cannot be used or inspected as product UI;
+- overstuffed screens that confuse priority and density;
+- sparse mockups that hide essential operational decisions;
+- translations that claim generated image quality, visual parity, or human
+  review without evidence.
+
+## Mind Philosophy
+
+1. A prototype is evidence for a product decision, not an illustration of a
+   feature list.
+2. Product strategy must arrive from the prompt pack; prompt2proto translates,
+   calibrates, and checks it.
+3. Multi-screen consistency is a technical contract from the prompt compiler;
+   density is a design judgment made during visual translation.
+4. Credible UI exposes object anatomy, states, actions, feedback, and trust
+   boundaries.
+5. The best prototype image prompt makes a reviewer understand what changed in
+   the user's workflow and why the product form deserves to exist.
+
+## Decision Heuristics
+
+- If a screen is high-risk or decision-heavy, make controls, provenance, and
+  consequences visible.
+- If a workflow repeats daily, optimize for scanning, comparison, and fast
+  next action.
+- If the industry is operational, financial, civic, clinical, or developer
+  tooling, allow denser inspectable surfaces when expert users compare objects,
+  owners, states, and consequences.
+- If the product is consumer-facing, emotionally sensitive, or mobile-first,
+  reduce visible density and make the next decision, reassurance, and control
+  clearer.
+- If a product centers on a domain object, make that object the visual anchor.
+- If a panel or drawer appears across screens, preserve its anatomy unless the
+  prompt pack explicitly changes the state.
+- If data is sensitive or automated, show human control before showing system
+  confidence.
+- If a prompt can fit any product after swapping nouns, it is not ready.
+
+## Guardrails
+
+- Do not invent product strategy missing from the prompt pack.
+- Do not start provider-backed image generation.
+- Do not perform human visual review or visual parity scoring.
+- Do not create proto2html, storyboard, motion, spec, change, or runtime
+  artifacts.
+- Do not let role language replace evidence gates.

package/skills/prompt2proto/references/01_input_contract.md

@@ -0,0 +1,53 @@
+# 01 Input Contract
+
+Use this reference before consuming a `PROTO_PROMPT_PACK`.
+
+## Required Input State
+
+The prompt pack must be ready for visual translation:
+
+- `prompt_text_manifest.status: ready_for_image_generation`
+- `prompt_text_manifest.paragraph_quality_status: pass`
+- `prompt_pack_integrity_gate.status: pass`
+- `prototype_reality_gate.status: pass`
+- `quality_rubric.prompt_executability.status: pass`
+- `post_validate.status: pass` for multi-direction packs, or `skipped` for an
+  explicit single-direction pack
+
+Every selected direction must provide:
+
+- product thesis and reason-to-exist;
+- target user transformation;
+- direction-level `prototype_prompt`;
+- screen prompts tied to `screen_manifest.target_screen_id`;
+- concrete data, copy, states, actions, system response, trust controls,
+  anti-goals, visual direction, and desired user feeling.
+
+## Refusal Output
+
+When an input fails, write a short refusal note or evidence entry with:
+
+- `status: refused`
+- failing gate or missing field
+- repair route: build-proto-prompt/vision2prompt
+- why prompt2proto cannot safely invent the missing content
+
+Do not silently repair strategic prompt text in this stage.
+
+## Boundary
+
+Allowed input interpretation:
+
+- choose which ready directions/screens to translate;
+- resolve output ordering and provider-agnostic image plan;
+- calibrate visual hierarchy, density, and component anatomy;
+- record blockers and handoff facts.
+
+Forbidden input expansion:
+
+- new strategic directions;
+- new validation target;
+- provider-specific generation;
+- visual acceptance claims;
+- HTML reconstruction;
+- specs, changes, runtime work, storyboard, or motion.

package/skills/prompt2proto/references/02_prompt_pack_readiness.md

@@ -0,0 +1,50 @@
+# 02 Prompt Pack Readiness
+
+Use this reference to check that the prompt pack can be translated without
+inventing missing strategy or screen system rules.
+
+## Readiness Checks
+
+Verify:
+
+- all required gates from `01_input_contract.md` pass;
+- `directions[].id` and `screen_prompts[].target_screen_id` resolve;
+- every screen prompt is standalone enough for a visual prototype stage;
+- screen prompts carry journey stage, interaction behavior, system response,
+  trust controls, anti-goals, visual direction, desired user feeling, and
+  concrete content;
+- `prototype_system_contract` states stable cross-screen invariants and allowed
+  state deltas before downstream visual translation starts;
+- product thesis, target user, primary loop, trust boundaries, and non-goals
+  are consistent across YAML and Markdown views.
+
+## Coherence Checks
+
+For multi-screen groups, identify the stable prototype system:
+
+- app shell and navigation taxonomy;
+- primary canvas and layout grid;
+- domain object vocabulary;
+- object drawer or detail panel anatomy;
+- action bar and command patterns;
+- audit, provenance, approval, privacy, or safety controls;
+- copy tone and data formatting;
+- allowed screen-specific state deltas.
+
+If the prompt pack lacks coherence constraints needed for multiple screens,
+record a blocker. Do not invent the contract downstream.
+
+## Handoff Shape
+
+Produce a concise readiness summary:
+
+```yaml
+prompt2proto_readiness:
+  status: pass|blocked
+  accepted_prompt_pack: path
+  selected_directions: []
+  selected_screen_ids: []
+  coherence_contract_status: present|missing|not_required
+  blockers: []
+  repair_route: build-proto-prompt
+```