@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/skills/prompt2proto/references/03_visual_translation_workflow.md

@@ -0,0 +1,64 @@
+# 03 Visual Translation Workflow
+
+Use this reference to translate ready prompt-pack content into UI/UX prototype
+instructions.
+
+## Translation Steps
+
+1. Restate the product decision being tested: product thesis, user
+   transformation, validation risk, and success signal.
+2. Select the product shell and primary canvas from the prompt pack; do not
+   replace it with a generic dashboard or chatbot unless justified there.
+3. Build the screen system: stable layout, navigation, object anatomy,
+   repeated panels, action zones, and trust surfaces.
+4. Apply the build-prototype philosophy engine before screen-by-screen work:
+   Chief PM identifies the user decision, product risk, domain object, and
+   evidence value; Principal UI/UX identifies the hierarchy, density, scan
+   path, affordances, and UI/UX credibility bar.
+5. For each screen, define:
+   - user goal and journey stage;
+   - visible domain objects;
+   - hierarchy from primary decision to supporting detail;
+   - component anatomy;
+   - state and selected object;
+   - user actions;
+   - system response;
+   - trust, privacy, approval, or audit controls;
+   - concrete sample data and copy;
+   - negative visual constraints.
+6. Calibrate density:
+   - visible when it changes the user's next decision;
+   - grouped when related fields need comparison;
+   - collapsed when secondary but still inspectable;
+   - delayed when it belongs after user intent;
+   - drilled into when it would overload the main canvas.
+7. Write provider-agnostic prototype instructions that preserve prompt-pack
+   strategy and add UI/UX specificity.
+
+## Density Calibration Rules
+
+- Operational tools may be dense when the user compares objects, owners,
+  statuses, risk, and next actions repeatedly.
+- Consumer or emotionally sensitive tools should reduce density when clarity,
+  confidence, or trust is the main behavior change.
+- High-risk actions need visible consequences and approval affordances.
+- AI outputs need provenance, editability, and user override when they affect
+  real decisions.
+- Mobile or constrained canvases require stronger prioritization; do not simply
+  shrink desktop density.
+
+## Output Pattern
+
+For every screen instruction, include:
+
+```text
+Screen: [name and id]
+Product reason: [why this screen exists]
+User decision: [what the user must understand or choose]
+Layout and hierarchy: [primary canvas, panels, density]
+Visible content: [objects, metrics, copy, labels]
+States and interactions: [current state, action, system response]
+Trust controls: [approval, audit, privacy, provenance, override]
+Negative constraints: [what must not appear]
+Acceptance: [what a reviewer must be able to inspect]
+```

package/skills/prompt2proto/references/04_output_contract.md

@@ -0,0 +1,67 @@
+# 04 Output Contract
+
+Use this reference when writing prompt2proto evidence or translation artifacts.
+
+## Translation Plan
+
+`PROMPT2PROTO_TRANSLATION_PLAN.md` should include:
+
+- source prompt pack path and readiness status;
+- role-engine summary;
+- selected directions and screen ids;
+- prototype system constants;
+- per-screen UI/UX translation instructions;
+- density decisions;
+- trust and approval surfaces;
+- negative constraints;
+- known limits and next handoff.
+
+## Evidence YAML
+
+`PROMPT2PROTO_EVIDENCE.yaml` should be provider-agnostic:
+
+```yaml
+schema_version: 0.1.0
+artifact_type: prompt2proto_evidence
+status: ready_for_generation|blocked
+source_prompt_pack: path
+role_engine:
+  chief_pm: applied
+  principal_ui_ux: applied
+readiness:
+  status: pass|blocked
+  blockers: []
+translation_outputs:
+  plan: PROMPT2PROTO_TRANSLATION_PLAN.md
+  selected_directions: []
+  selected_screen_ids: []
+prototype_system:
+  coherence_contract_status: present|missing|not_required
+  stable_elements: []
+density_calibration:
+  visible: []
+  grouped: []
+  collapsed: []
+  delayed: []
+handoff:
+  next_allowed_stage: provider_generation|prompt_pack_repair|review_blocked
+  forbidden_claims: []
+```
+
+## Future Image Metadata
+
+When a later queue authorizes provider generation, every generated image must
+record:
+
+- `image_id`
+- `direction_id`
+- `prompt_id`
+- `screen_name`
+- `path`
+- `source_prompt_ref`
+- `generated_at`
+- `generator`
+- `generation_status`
+- `review_status`
+
+Images without metadata are not valid prototype evidence.

package/skills/prompt2proto/references/05_quality_rubric.md

@@ -0,0 +1,46 @@
+# 05 Quality Rubric
+
+Use this reference before handoff.
+
+## Pass Criteria
+
+Pass only when:
+
+- prompt-pack readiness gates pass or blockers are explicitly recorded;
+- translation preserves product thesis, target user transformation, primary
+  loop, trust boundaries, and non-goals;
+- screen coherence is consumed from the prompt pack or blocked when missing;
+- density decisions are justified by industry, role, risk, screen size, task
+  frequency, and user attention;
+- every screen instruction names user decision, layout hierarchy, visible
+  content, state behavior, system response, trust controls, negative
+  constraints, and acceptance checks;
+- output clearly states that provider generation, human visual review, visual
+  parity, proto2html, storyboard, motion, specs, changes, and runtime work are
+  out of scope unless separately authorized.
+
+## Failures
+
+Fail when:
+
+- the output invents product strategy;
+- density is treated as more text rather than design prioritization;
+- multi-screen consistency is repaired downstream instead of sourced from the
+  prompt pack;
+- the prototype looks like a generic dashboard, card wall, report, chatbot, or
+  poster without strategic justification;
+- trust controls are mentioned but not placed in UI;
+- generated image quality or visual parity is claimed without evidence.
+
+## Final Check
+
+Before completing, search the output for unsupported claims:
+
+- "generated image quality passed"
+- "visual parity passed"
+- "human reviewed"
+- "ready for proto2html"
+- "storyboard complete"
+- "motion model"
+
+Remove or block those claims unless a later authorized artifact proves them.

package/skills/proto2html/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: proto2html
+description: Reconstruct an accepted benchmark prototype image or screen group into a single-file HTML prototype with fidelity evidence. Use when the user wants the post-proto `/ow:proto2html` source behavior, benchmark-to-HTML reconstruction, screenshot comparison, or fidelity-report handoff before html2spec or production work.
+---
+
+# Proto2html
+
+## Purpose
+
+Reconstruct an accepted benchmark prototype image or accepted screen group into
+one local single-file HTML prototype with fidelity evidence.
+
+Proto2html is a reconstruction step. It should preserve the accepted benchmark
+as faithfully as practical. It must not explore new product directions, generate
+new prototype images, create specs, or start production implementation.
+
+## Inputs
+
+Required:
+
+- accepted benchmark prototype image, accepted generated image set, accepted
+  screen group, or accepted refined prompt output
+- source prototype evidence or review notes that explain why the benchmark was
+  accepted
+
+Optional:
+
+- `references/proto2html-artifact-contracts.md`
+- `schemas/html-prototype.schema.json`
+- source `PROTO_PROMPT_PACK.yaml` or `REFINED_PROTO_PROMPT_PACK.yaml`
+- decision record or review evidence with accepted/rejected elements
+- target viewport constraints, browser constraints, language, or accessibility
+  requirements
+
+Do not load unrelated specs, changes, runtime state, generated adapters, build
+plans, or production implementation history unless the reconstruction question
+explicitly depends on them.
+
+## Output
+
+Write artifacts under the active HTML prototype or change path chosen by the
+workflow. The source artifact should match `schemas/html-prototype.schema.json`.
+
+Expected files:
+
+```text
+HTML_PROTOTYPE.yaml
+prototype.html
+FIDELITY_REPORT.yaml
+screenshots/
+SUMMARY.yaml
+```
+
+For source-level dogfood before runtime exposure, the same evidence may live
+under the selected change folder.
+
+## Workflow
+
+1. Resolve benchmark input. Require accepted image or screen-group evidence.
+   If acceptance is missing, stop and return to `/ow:proto` or `/ow:tune`.
+2. Load prompt lineage and review notes only as needed to preserve intent.
+3. Define reconstruction scope: screens, states, viewport targets, include
+   rules, and explicit exclusions.
+4. Implement one single-file `prototype.html` focused on visual and interaction
+   fidelity to the accepted benchmark.
+5. Avoid production architecture: no app scaffolding, backend, persistence,
+   auth, deployment config, package installs, or broad component systems.
+6. Render the HTML locally when practical and capture screenshot evidence.
+7. Compare screenshots to benchmark refs and write fidelity gaps.
+8. Write `HTML_PROTOTYPE.yaml` and `FIDELITY_REPORT.yaml`.
+9. Run repository validation when available.
+
+## Reconstruction Rules
+
+- Preserve benchmark information architecture, hierarchy, layout rhythm,
+  component vocabulary, copy tone, states, and trust controls.
+- Use static or hardcoded sample data from the benchmark unless the user
+  explicitly asks for lightweight interaction.
+- Implement only interactions visible or implied by the benchmark review.
+- Prefer direct HTML/CSS/JS in one file for reviewability.
+- Keep code readable enough for later spec extraction, but do not turn it into
+  production architecture.
+- Record deviations as fidelity gaps instead of silently changing the product.
+
+## Evidence Rules
+
+`HTML_PROTOTYPE.yaml` should capture:
+
+- source prototype evidence and accepted decision refs
+- benchmark image or screen refs
+- reconstruction include/exclude scope
+- `html_artifact.path`, `html_artifact.type: single_file_html`, and entrypoint
+- render targets
+- fidelity benchmark refs, screenshot refs, matched elements, gaps, and browser
+  checks
+- known limits
+- result and handoff
+
+`FIDELITY_REPORT.yaml` should be optimized for review:
+
+- what matches the benchmark
+- what differs
+- severity of each gap
+- whether gaps block `/ow:html2spec`
+- recommended next command
+
+## Quality Gate
+
+Revise before finishing if:
+
+- no accepted benchmark evidence is named
+- the HTML introduces a new product direction
+- key benchmark hierarchy, copy, states, trust controls, or layout are missing
+- fidelity gaps are hidden or too vague to act on
+- the artifact becomes a production app or spec instead of a reconstruction
+- screenshots or review notes are absent when local rendering was practical
+
+## Forbidden Defaults
+
+- Do not generate new prototype images.
+- Do not tune visual direction; return to `tune-prototype` for that.
+- Do not create `TECH_SPEC`, `FRONTEND_SPEC`, `BACKEND_SPEC`, `API_SPEC`, or
+  build plans.
+- Do not add `/ow:proto2html` runtime command surfaces.
+- Do not edit generated `.agents/` or `.openworkflow/` surfaces.
+- Do not add auth, persistence, deployment, package scaffolding, or backend
+  behavior.
+
+## Handoff
+
+Expected outcomes:
+
+- `accepted`: hand off to `/ow:html2spec`
+- `needs_reconstruction`: run another proto2html pass
+- `return_to_tune`: benchmark needs visual refinement first
+- `blocked`: accepted benchmark or rendering evidence is missing

package/skills/proto2html/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Proto2html"
+  short_description: "Reconstruct accepted prototype benchmarks into single-file HTML"
+  default_prompt: "Use /ow:proto2html source behavior to reconstruct an accepted benchmark prototype image or screen group into a single-file HTML prototype with fidelity evidence."

package/skills/proto2html/references/proto2html-protocol.md

@@ -0,0 +1,115 @@
+# Proto2html Protocol
+
+Use this reference when converting accepted benchmark prototype evidence into a
+single-file HTML reconstruction.
+
+## Input Resolution
+
+Require one accepted benchmark source:
+
+- accepted benchmark image path
+- accepted generated image set with selected benchmark id
+- accepted screen group
+- accepted refined prompt pack with generated image refs
+
+Also capture:
+
+- source prototype evidence ref
+- prompt pack ref when available
+- decision or review evidence that accepted the benchmark
+- include and exclude reconstruction scope
+- viewport targets
+
+If acceptance is unclear, stop. Do not infer acceptance from the mere existence
+of images or prompts.
+
+## Reconstruction Scope
+
+Before writing HTML, state:
+
+- screens and states to reconstruct
+- viewport targets
+- interaction states that matter for fidelity
+- benchmark elements that must be preserved
+- elements explicitly excluded
+- assumptions caused by missing evidence
+
+Scope should be smaller than a product app. It should be enough to reconstruct
+the accepted benchmark for review and later spec extraction.
+
+## Single-File HTML Rules
+
+Prefer one `prototype.html` with inline CSS and small inline JavaScript only
+when needed for benchmark-visible interaction states.
+
+Allowed:
+
+- static hardcoded content
+- local image refs
+- CSS responsive rules for named render targets
+- minimal JS for visible states, toggles, tabs, or prototype-only transitions
+
+Avoid:
+
+- package managers
+- framework scaffolds
+- backend or API calls
+- persistence
+- auth
+- deployment files
+- production component architecture
+
+## Fidelity Report
+
+Capture fidelity evidence in a compact YAML report:
+
+```yaml
+schema_version: 0.1.0
+artifact_type: fidelity_report
+benchmark_refs: []
+screenshot_refs: []
+matched_elements: []
+gaps:
+  - gap_id: FID001
+    severity: low|medium|high|blocking
+    description: ""
+    disposition: accept|repair|return_to_tune
+browser_checks: []
+known_limits: []
+recommendation: accepted|needs_reconstruction|return_to_tune|blocked
+```
+
+Gaps should be concrete enough for the next agent to repair or accept without
+re-reading all raw evidence.
+
+## HTML Prototype Artifact
+
+`HTML_PROTOTYPE.yaml` should follow
+`schemas/html-prototype.schema.json` and include:
+
+- `artifact_type: html_prototype`
+- `source_prototype`
+- `benchmark`
+- `reconstruction_scope`
+- `html_artifact`
+- `render_targets`
+- `fidelity`
+- `known_limits`
+- `result`
+- `handoff.next_command`
+
+Use `result: accepted` only when fidelity gaps do not block spec extraction.
+The normal accepted handoff is `/ow:html2spec`.
+
+## Quality Gate
+
+Revise before finishing if:
+
+- benchmark evidence is not explicitly accepted
+- HTML output is not single-file
+- visual hierarchy diverges from the benchmark without a recorded reason
+- important benchmark copy or trust controls are missing
+- viewport targets are undefined
+- screenshot or browser evidence is missing when rendering was practical
+- fidelity gaps are absent, generic, or unactionable
+- output drifts into engineering spec or production implementation

package/skills/run-team/SKILL.md

@@ -55,10 +55,14 @@ On `/ow:team CONTENT`, do not start coding immediately.
    - Immediately record the returned `agent_id` in `AGENT_ROSTER.yaml` and the task entry.
    - Keep persistent implementation agents mounted across related atom tasks and issue-fix loops.
    - Use event-driven review, security, QA, and git-release agents asynchronously where ownership is disjoint.
+   - For source-edit work, apply coder governance before completion: owner/file
+     map, RED evidence when applicable, GREEN evidence after edits,
+     post-write self-check, validation ladder, and evidence binding.
 
 8. Checkpoint.
    - Update runtime state after every real state transition.
    - Run required checks.
+   - Record coder evidence status for source-edit work.
    - Commit coherent runtime/implementation/QA slices, or record why a checkpoint is deferred.
 
 ## Runtime Rules

package/skills/select-change/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: select-change
+description: Select, inspect, or prepare one implementable OpenWorkflow candidate change from CANDIDATE_CHANGES.yaml and create SELECTED_CHANGE.yaml, ATOM_TASKS.yaml, and IMPLEMENTATION_BRIEF.md. Use when a candidate queue exists and the user wants the next focused change prepared for implementation, or when a specific candidate id needs readiness review before selection.
+---
+
+# Select Change
+
+## Purpose
+
+Choose one candidate change and turn it into implementation-ready planning
+artifacts. This skill prepares the next change; it does not execute the
+implementation.
+
+By default, operate on one active queue and rank candidates inside that queue.
+Use cross-queue arbitration only when the user provides multiple queues, points
+to a cross-queue `CHANGE_ANALYSIS.yaml`, or asks which queue and candidate
+should go next.
+
+SC is not only a "mark selected" command. In a single queue it owns
+prioritization, readiness review, risk gating, selection, and atomization.
+
+## Feat Boundary
+
+The source `CANDIDATE_CHANGES.yaml` is the feat boundary. A selected candidate
+is a commit-sized slice inside that feat, not a new top-level feat. By default,
+write selection artifacts under the existing queue folder:
+
+```text
+changes/<plan_id>/<candidate-id>-<slug>/
+  SELECTED_CHANGE.yaml
+  ATOM_TASKS.yaml
+  IMPLEMENTATION_BRIEF.md
+```
+
+Create a new top-level `changes/<id>/` only when the user explicitly starts a
+new decomposition queue or the existing queue is no longer the owning feat.
+
+## Git Boundary
+
+Use `git status --short --branch` as a read-only guard before selection.
+
+If the queue has `queue_policy.branch_boundary`, compare it with the current
+branch. When they differ, stop before creating selection artifacts unless the
+user explicitly says this is a planning-only exception or asks to proceed on the
+current branch. Do not switch branches from this skill.
+Also compare feat identity: a branch boundary that names another plan id is not
+the owning feat branch just because it equals the current branch. Proceed only
+when the queue records an explicit `branch_identity_exception` for temporary
+continuation, or stop and surface the mismatch.
+
+If the working tree is dirty, inspect whether the changes are only the current
+selection operation. If the dirty tree appears to contain an uncommitted
+previous selected change or unrelated implementation work, stop and recommend
+committing, stashing, or resolving that work before selecting another
+candidate. Do not commit, stash, reset, restore, or clean from this skill.
+
+## Read First
+
+Read these only as needed:
+
+- `references/planning-artifact-contracts.md`
+- `skills/select-change/references/selection-protocol.md`
+- The target `CANDIDATE_CHANGES.yaml`
+- The matching `CANDIDATE_CHANGES.md` only as a readable aid
+- `CHANGE_ANALYSIS.yaml` only when consuming a cross-queue recommendation
+
+## Workflow
+
+1. Run `git status --short --branch` and note current branch and dirty paths.
+2. Read `CANDIDATE_CHANGES.yaml` as the source of truth.
+3. Check `queue_policy.branch_boundary` when present. Stop on branch mismatch
+   unless the user has approved a planning-only exception.
+   If the branch boundary names another plan id, require an explicit temporary
+   continuation exception before treating the branch as acceptable.
+4. Check dirty-tree state. Stop if uncommitted work would contaminate a new
+   selected change or blur the one-change-one-commit boundary.
+5. If the user names a candidate id, perform targeted readiness review for
+   that id before considering the rest of the queue.
+6. If the user provides multiple queues or a cross-queue `CHANGE_ANALYSIS.yaml`,
+   run the cross-queue arbitration path before choosing a target queue.
+7. Filter candidates to `ready` first. If none are ready, inspect `candidate`
+   entries and report the blockers instead of forcing a selection.
+8. Rank the current queue directly:
+   - prefer `next_recommended_candidate_id` when it points to a ready candidate
+     and dependencies still hold
+   - otherwise prefer dependency-satisfied candidates that best match
+     `selection_policy`
+   - then prefer unlock value, focused owned paths, realistic validation,
+     lower risk, and user recency
+9. Choose exactly one candidate from the owning queue.
+10. If the candidate is `risk: high`, stop before selection unless the user has
+   explicitly approved a concrete decision option from a high-risk decision
+   report.
+11. Create a candidate-specific folder inside the current feat folder, usually
+   `changes/<plan_id>/<candidate-id>-<slug>/`.
+12. Write `SELECTED_CHANGE.yaml`, `ATOM_TASKS.yaml`, and
+   `IMPLEMENTATION_BRIEF.md`.
+13. Update the candidate queue:
+   - set the selected candidate to `selected`
+   - add `selection.selected_change_id`
+   - add concise `selection.reason`
+   - append an `operations` entry for the selection
+   - leave all other candidates in place
+14. Refresh `CANDIDATE_CHANGES.md` from the YAML facts.
+15. Stop before implementation unless the user explicitly asks to continue.
+
+## Cross-Queue Arbitration
+
+Cross-queue arbitration is explicit and exceptional. Do not discover every
+queue in the repo unless the user asks for a global comparison or provides an
+existing cross-queue `CHANGE_ANALYSIS.yaml`.
+
+Do not invoke `analyze-changes` for a normal single-queue selection. The
+single-queue path above is the default and should be sufficient for
+prioritizing candidates inside one `CANDIDATE_CHANGES.yaml`.
+
+When arbitration is active:
+
+- Prefer an existing `CHANGE_ANALYSIS.yaml` produced by `analyze-changes`.
+- Confirm the recommended `target_plan_id` and `target_candidate_id` still
+  exist, are not done, and satisfy dependencies.
+- Re-run branch-boundary, dirty-tree, and high-risk gates against the target
+  queue before writing selection artifacts.
+- Keep selection artifacts inside the target queue folder, not inside the
+  analysis folder.
+- Record rejected alternatives in `SELECTED_CHANGE.yaml` with `plan_id`,
+  `candidate_id`, and a concise reason.
+- If no candidate is clearly safe to select, stop and recommend queue
+  maintenance, a high-risk report, or a fresh `analyze-changes` run.
+
+Use a separate meta-selection artifact only when the user's requested output is
+itself an analysis or governance decision. Normal implementation selection
+should select one candidate inside the target queue.
+
+## Targeted Review
+
+When reviewing a specific candidate id, report:
+
+- current status and readiness
+- dependencies and whether each is satisfied
+- owned paths and likely conflict surfaces
+- validation commands
+- acceptance gaps
+- high-risk decision report status when `risk: high`
+- blockers or reasons it should not be selected
+- exact queue maintenance operation needed, if any
+
+Do not select a candidate during targeted review unless the user asks to select
+or the current workflow explicitly requires selection.
+
+## High-Risk Stop Gate
+
+For any `risk: high` candidate, do not create `SELECTED_CHANGE.yaml`,
+`ATOM_TASKS.yaml`, or `IMPLEMENTATION_BRIEF.md` unless the user explicitly
+approves a concrete decision option from a `HIGH_RISK_DECISION_REPORT.md`.
+
+When a high-risk candidate is next:
+
+- Report the candidate id, title, status, and why it is high risk.
+- Reference the existing `HIGH_RISK_DECISION_REPORT.md` when present.
+- If no report exists, instruct `decompose-to-changes` or queue maintenance to
+  create one under the owning queue folder.
+- Name the decision options and recommended path from the report when known.
+- State the exact resume condition: user approval of a concrete option.
+- Leave the candidate status unchanged unless the user asks to block, defer, or
+  supersede it.
+
+If the user explicitly approves a high-risk option, the selection reason must
+name the approved option and the guardrails from the report. Keep atom tasks
+narrow enough to match that approved option.
+
+## Atom Task Rules
+
+- Create tasks that map to coherent owned paths.
+- Keep each task small enough for one focused implementation pass.
+- Use `read`, `edit`, `document`, and `verify` task types.
+- Include `done_when` criteria that an implementation agent can verify.
+- Add forbidden paths in `SELECTED_CHANGE.yaml` when generated or unrelated
+  surfaces should not be touched.
+- For source-edit candidates, include coder preflight expectations: source
+  truth, generated surfaces, owned paths, forbidden paths, RED/GREEN evidence
+  when applicable, post-write self-check, validation ladder, and evidence
+  binding.
+
+## Selection Boundaries
+
+- Do not delete or renumber candidate ids.
+- Do not silently select a blocked candidate.
+- Do not silently select a `risk: high` candidate.
+- Do not select on the wrong branch without explicit planning-only approval.
+- Do not select when unrelated dirty-tree work would contaminate the commit boundary.
+- Do not implement the selected change.
+- Do not create commits, switch branches, stash, reset, restore, or clean.
+- Do not mark the candidate `done`; implementation completion owns that update.
+- Do not widen scope beyond the selected candidate.
+- Do not hand-edit generated `.agents/` or `.openworkflow/` surfaces unless the
+  selected candidate explicitly owns those paths and the user accepts that
+  scope.
+- Do not treat coder governance as a replacement for selection. Selection owns
+  the implementation boundary; coder governance constrains later source edits.

package/skills/select-change/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Select Change"
+  short_description: "Choose and prepare one focused change."
+  default_prompt: "Read a CANDIDATE_CHANGES queue, select the best next change, and create SELECTED_CHANGE, ATOM_TASKS, and IMPLEMENTATION_BRIEF artifacts."