@tiic-tech/openworkflow 0.1.0 → 0.1.2

package/skills/analyze-changes/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: analyze-changes
+description: Analyze multiple OpenWorkflow CANDIDATE_CHANGES queues and recommend the next plan id and candidate id without selecting or implementing it. Use when multiple candidate queues exist, when cross-queue priority is unclear, or before select-change should consume a cross-queue recommendation.
+---
+
+# Analyze Changes
+
+## Purpose
+
+Compare multiple candidate queues and produce a read-only priority analysis. This skill
+does not decompose new queues, does not select a candidate, and does not
+implement code.
+
+Do not use this skill as a mandatory pre-step for a single active queue. When
+the current work state has one owning `CANDIDATE_CHANGES.yaml`, use
+`select-change` directly; SC owns single-queue prioritization and selection.
+
+## Read First
+
+Read only what is needed:
+
+- `references/planning-artifact-contracts.md`
+- `references/git-version-control-governance.md`
+- `references/issue-governance.md` when Issues affect priority
+- `skills/analyze-changes/references/analysis-protocol.md`
+- The target `CANDIDATE_CHANGES.yaml` files, plural
+
+## Workflow
+
+1. Run `git status --short --branch` and record the current branch and dirty
+   tree state.
+2. Confirm the request is a cross-queue decision. If there is only one active
+   queue and no explicit cross-queue comparison request, stop and hand off to
+   `select-change` without writing `CHANGE_ANALYSIS.yaml`.
+3. Discover candidate queues only from user-provided paths or obvious
+   `changes/*/CANDIDATE_CHANGES.yaml` files when the user asks for a global
+   analysis.
+4. Read YAML as the source of truth. Use Markdown views only as readable aids.
+5. For each queue, record branch boundary, next recommended candidate, ready
+   candidates, blocked candidates, high-risk candidates, and dependency gaps.
+6. Score candidates with the queue policy first, then cross-queue signals:
+   readiness, dependency unlock value, risk, branch fit, dirty-tree fit,
+   Issue linkage, validation realism, and user recency.
+7. If the best next candidate is `risk: high`, stop with a high-risk analysis
+   recommendation and point to the needed `HIGH_RISK_DECISION_REPORT.md`.
+8. Write `CHANGE_ANALYSIS.yaml` first, then `CHANGE_ANALYSIS.md` as a readable
+   view.
+9. Recommend exactly one `target_plan_id` and `target_candidate_id` when the
+   evidence supports it. Otherwise recommend the queue maintenance needed before
+   selection.
+10. Hand off to `select-change`; do not create `SELECTED_CHANGE.yaml`,
+   `ATOM_TASKS.yaml`, or `IMPLEMENTATION_BRIEF.md`.
+
+## Output Location
+
+Default to an analysis folder when comparing multiple queues:
+
+```text
+changes/<analysis-id>/
+  CHANGE_ANALYSIS.yaml
+  CHANGE_ANALYSIS.md
+```
+
+Use an `analysis-id` that describes the decision episode, not a selected
+candidate.
+
+## Recommendation Rules
+
+- Prefer ready candidates over blocked or candidate-status entries.
+- Prefer a queue's `next_recommended_candidate_id` when it is ready and its
+  dependencies still hold.
+- Prefer candidates that unlock multiple downstream changes.
+- Prefer candidates whose branch boundary matches the current branch.
+- Treat unrelated dirty-tree work as a reason to pause or recommend committing
+  the current selected change first.
+- Do not recommend a high-risk candidate for selection unless the user has
+  explicitly approved a concrete option from a high-risk decision report.
+- If multiple queues are active and none is clearly superior, recommend the
+  smallest queue maintenance step that will make selection safe.
+
+## Boundaries
+
+- Do not create or modify candidate queues except to add an explicit analysis
+  evidence link when the user requests that maintenance.
+- Do not select candidates.
+- Do not implement candidates.
+- Do not produce a same-queue priority analysis when `select-change` can rank
+  candidates inside the only active queue.
+- Do not run destructive git operations.
+- Do not run gh mutation operations.
+- Do not treat local Issue snapshots as authoritative when GitHub Issues are
+  configured as the source of truth.

package/skills/analyze-changes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Analyze Changes"
+  short_description: "Prioritize across candidate change queues."
+  default_prompt: "Analyze one or more CANDIDATE_CHANGES queues and recommend the next plan id and candidate id without selecting or implementing it."

package/skills/analyze-changes/references/analysis-protocol.md

@@ -0,0 +1,116 @@
+# Analysis Protocol
+
+Use this protocol to produce cross-queue `CHANGE_ANALYSIS.yaml` and
+`CHANGE_ANALYSIS.md`.
+
+`analyze-changes` is for cross-queue priority arbitration. If the current work
+state has one active `CANDIDATE_CHANGES.yaml`, do not create a
+`CHANGE_ANALYSIS.yaml` just to choose the next candidate. Hand off to
+`select-change`; SC owns prioritization inside one queue.
+
+## Inputs
+
+Accepted inputs:
+
+- explicit `CANDIDATE_CHANGES.yaml` paths, plural
+- a request to analyze all obvious queues under `changes/`
+- Issue references only when they are already linked from candidate queues or
+  supplied by the user
+
+Do not load generated runtime surfaces or unrelated source code unless a queue's
+candidate explicitly needs that context for readiness analysis.
+
+## Candidate Evaluation
+
+First confirm that at least two active queues are being compared, or that the
+user explicitly requests cross-queue arbitration. If not, return a handoff to
+`select-change` instead of writing analysis artifacts.
+
+For each candidate considered, capture:
+
+- `plan_id`
+- `candidate_id`
+- `status`
+- `risk`
+- dependencies and whether they are satisfied
+- branch boundary and whether it matches the current branch
+- dirty-tree conflict risk
+- owned paths
+- validation commands
+- downstream unlocks
+- Issue refs when present
+- high-risk report status when risk is high
+
+## Priority Signals
+
+Use these signals in order:
+
+1. User-explicit target or most recent instruction.
+2. Candidate readiness and dependency satisfaction.
+3. Queue `next_recommended_candidate_id`.
+4. Risk gate: high-risk candidates require report and explicit approval.
+5. Unlock value for downstream candidates.
+6. Branch and dirty-tree fit.
+7. Validation realism.
+8. Issue or PR urgency when documented in the queue.
+
+Do not hide tradeoffs. Name rejected alternatives and why they were not chosen.
+
+## YAML Shape
+
+`CHANGE_ANALYSIS.yaml` should include:
+
+```yaml
+schema_version: 0.1.0
+contract_id: change_analysis:<analysis-id>
+contract_type: planning
+planning_artifact_type: change_analysis
+analysis_id: <analysis-id>
+status: complete
+source:
+  queues:
+    - changes/<plan_id>/CANDIDATE_CHANGES.yaml
+git_state:
+  branch: <branch-name>
+  dirty: false
+recommendation:
+  target_plan_id: <plan-id>
+  target_candidate_id: <candidate-id>
+  action: handoff_to_select_change
+  reason: <short reason>
+rejected_alternatives:
+  - plan_id: <plan-id>
+    candidate_id: <candidate-id>
+    reason: <short reason>
+high_risk_stop:
+  required: false
+validation:
+  commands_run:
+    - git status --short --branch
+```
+
+If no candidate should be selected yet, set `recommendation.action` to
+`queue_maintenance`, `high_risk_report`, or `commit_current_work` and explain
+the blocker.
+
+## Markdown Shape
+
+`CHANGE_ANALYSIS.md` should include:
+
+- source-of-truth notice
+- queues analyzed
+- git state
+- recommended target
+- rejected alternatives
+- blockers or high-risk stop conditions
+- exact handoff instruction for `select-change`
+
+## High-Risk Handling
+
+If the top candidate is high risk:
+
+- do not recommend selection
+- name the high-risk candidate and report path
+- state whether the report exists
+- recommend creating or updating `HIGH_RISK_DECISION_REPORT.md` if missing
+- state the resume condition as explicit user approval of a concrete option

package/skills/build-proto-prompt/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: build-proto-prompt
+description: Compile proto-ready vision and validation into ready PROTO_PROMPT_PACK artifacts. Use for the internal /ow:build-proto-prompt prompt-pack compiler boundary before prompt2proto, image generation, visual review, proto2html, specs, changes, or runtime work.
+---
+
+# Build Proto Prompt
+
+## Purpose
+
+Compile durable vision and validation inputs into ready strategic prototype
+prompt packs. This source skill owns the prompt-pack compiler boundary that was
+previously embedded in `build-prototype`.
+
+`build-proto-prompt` does not generate images, review visual output, build
+HTML, create specs, or start implementation. It writes high-quality
+`PROTO_PROMPT_PACK` artifacts that can be consumed by `prompt2proto`.
+
+## Role Engine
+
+Before compiling prompts, adopt the Co-Founder plus Chief PM / senior product
+strategist role engine:
+
+- Co-Founder: protects product thesis, user transformation, differentiated
+  product form, reason-to-exist, and ambition.
+- Chief PM: protects validation fit, risk reduction, user decision context,
+  product-system completeness, handoff readiness, and no-go boundaries.
+
+The references are tools for this role engine, not a checklist that proves
+quality by itself.
+
+## Inputs
+
+Required:
+
+- durable vision contract or equivalent direct user vision
+- durable validation target
+- resolved strategic direction count from the prototype orchestration preflight
+
+Optional:
+
+- context map or glossary
+- target platform, canvas, tool, fidelity, language, brand, or acceptance bar
+- existing prototype prompt pack only when repairing a failed prompt-pack gate
+
+## References
+
+Run these references in order:
+
+1. `references/prompt-pack-compiler-protocol.md`
+2. `references/output-boundary.md`
+
+Until the compiler references are fully split, reuse the OW-owned
+`skills/build-prototype/references/strategic-prompt-pack-protocol.md` and
+`skills/build-prototype/references/vision2prompt/01_input_contract.md` through
+`07_quality_rubric.md` as the detailed prompt-generation toolkit.
+
+## Output
+
+Write prompt-pack artifacts under the active prototype folder:
+
+```text
+PROTO_PROMPT_PACK.yaml
+PROTO_PROMPT_PACK.md
+REVIEW_PLAN.md
+EVIDENCE.yaml
+NOTE.md
+```
+
+The YAML prompt pack is the source of truth. Markdown is the readable view.
+
+## Workflow
+
+1. Confirm durable vision and validation inputs are present and strong enough.
+2. Normalize product domain, target user, usage context, current alternative,
+   core pain, behavior change, success signal, differentiator, trust
+   boundaries, non-goals, and validation target.
+3. Apply the Co-Founder plus Chief PM role engine before generating directions.
+4. Infer product experience model: archetype, primary canvas, information
+   architecture, domain objects, task loop, state model, data realism, visual
+   language, anti-generic constraints, and category quality bar.
+5. Write `prototype_system_contract` before screen prompts: stable app shell,
+   navigation taxonomy, data vocabulary, domain object anatomy, object detail
+   anatomy, action bar, audit/trust pattern, copy tone, and allowed
+   screen-specific deltas.
+6. Generate candidate strategic hypotheses, then select materially distinct
+   directions based on product form, trigger, interaction model, emotional
+   driver, retention mechanism, validation metric, and main risk.
+7. Write dailin-grade direction and screen prompt paragraphs with journey,
+   screen components, interaction behavior, system response, concrete content,
+   trust controls, anti-goals, visual direction, desired user feeling, product
+   thesis, reason-to-exist, and user transformation.
+8. Run prompt-pack readiness gates: integrity, prototype reality, prompt
+   executability, paragraph quality, screen manifest linkage, and
+   post-validation.
+9. Set `prompt_text_manifest.status: ready_for_image_generation` only when all
+   readiness gates and the prototype system contract pass.
+10. Keep `image_generation.status: not_started` and hand off to `prompt2proto`
+   only after prompt-pack readiness passes.
+
+## Boundary
+
+Allowed:
+
+- compile strategic prompt packs;
+- define prototype system coherence before visual translation;
+- repair prompt-pack text when readiness gates fail;
+- write review plan and evidence about prompt readiness;
+- preserve no-go constraints for downstream stages.
+
+Forbidden:
+
+- provider-backed image generation;
+- human visual review;
+- visual reference parity scoring;
+- proto2html;
+- storyboard or motion modeling;
+- production design/spec/change/runtime work;
+- narrowing `build-prototype` behavior.
+
+## Handoff
+
+When all gates pass, hand internally to `prompt2proto` with a ready prompt
+pack. When gates fail, keep `image_generation.status: not_started`, record the
+failed gate, and repair inside `build-proto-prompt` instead of downstreaming a
+thin prompt pack.

package/skills/build-proto-prompt/references/output-boundary.md

@@ -0,0 +1,54 @@
+# Output Boundary
+
+Use this reference to keep `build-proto-prompt` from crossing into downstream
+prototype consumption.
+
+## Owns
+
+- strategic prompt-pack compilation;
+- product experience model extraction;
+- prototype system coherence contract;
+- direction and screen prompt text;
+- prompt-pack readiness gates;
+- review plan for prompt evidence;
+- handoff facts for `prompt2proto`.
+
+## Does Not Own
+
+- provider image generation;
+- UI/UX visual translation from ready prompt packs;
+- density calibration after prompt-pack readiness;
+- human visual review;
+- visual reference parity;
+- proto2html;
+- storyboard or motion;
+- production specs, changes, teams, or runtime state.
+
+## Handoff Contract
+
+When ready:
+
+```yaml
+prompt_text_manifest:
+  status: ready_for_image_generation
+  paragraph_quality_status: pass
+prototype_system_contract:
+  stable_app_shell:
+    - persistent product frame is defined
+  allowed_screen_deltas:
+    - state-specific changes are explicit
+image_generation:
+  status: not_started
+internal_pipeline:
+  next_stage: prompt2proto
+```
+
+When blocked:
+
+```yaml
+prompt_text_manifest:
+  status: blocked
+image_generation:
+  status: not_started
+repair_route: /ow:build-proto-prompt
+```

package/skills/build-proto-prompt/references/prompt-pack-compiler-protocol.md

@@ -0,0 +1,80 @@
+# Prompt-Pack Compiler Protocol
+
+Use this reference when `build-proto-prompt` compiles durable vision and
+validation into a `PROTO_PROMPT_PACK`.
+
+## Role Coupling
+
+The Co-Founder lens asks what product should exist and why this prototype is
+worth generating. It rejects generic dashboards, card walls, chatbots, report
+screens, and visual skins when those forms do not express the product thesis.
+
+The Chief PM lens asks whether the prompt pack will reduce the validation risk.
+It protects include/exclude scope, user decision context, success signals,
+trust boundaries, and handoff readiness.
+
+## Required Compiler Outputs
+
+The prompt pack should include:
+
+- normalized input;
+- strategic core;
+- prototype brief;
+- product experience model;
+- prototype system contract;
+- screen manifest;
+- global design system prompt;
+- direction-level prototype prompts;
+- screen-bound prompts;
+- quality rubric;
+- prompt text manifest;
+- prompt-pack integrity gate;
+- prototype reality gate;
+- post-validate gate;
+- image generation state set to `not_started`;
+- review plan.
+
+## Readiness Rules
+
+Do not mark the prompt pack ready until:
+
+- prompt paragraphs are dailin-grade long-form prototype-generation briefs;
+- `prototype_system_contract` states cross-screen invariants separately from
+  screen-specific state deltas;
+- every direction has product thesis, user transformation, reason-to-exist,
+  differentiated product form, and PM judgment;
+- screen prompts resolve to screen manifest ids;
+- screen prompts include journey, interaction behavior, system response, trust
+  controls, anti-goals, visual direction, desired user feeling, and concrete
+  content;
+- integrity, prototype reality, prompt executability, paragraph quality, and
+  post-validation gates pass.
+
+## Repair Rule
+
+If a gate fails, repair the prompt pack in this compiler stage. Do not route
+thin or incoherent prompt text to `prompt2proto`.
+
+## Prototype System Contract
+
+Write this contract before screen prompts so downstream visual translation
+knows what must stay stable across screens:
+
+- `stable_app_shell`: persistent frame, navigation, header, workspace regions,
+  and canvas behavior.
+- `navigation_taxonomy`: sections, routes, tabs, modules, or modes that should
+  not drift between screens.
+- `data_vocabulary`: domain objects, field names, status labels, metric names,
+  and formatting rules.
+- `domain_object_anatomy`: what makes each core object recognizable.
+- `object_detail_anatomy`: detail drawer, side panel, inspector, or modal
+  structure that repeats across states.
+- `action_bar_contract`: primary and secondary action placement, labels,
+  confirmation patterns, and disabled states.
+- `audit_trust_pattern`: provenance, approval, privacy, safety, audit, and
+  human-control surfaces.
+- `copy_tone`: stable tone for operational text and AI/system copy.
+- `allowed_screen_deltas`: what may change by journey stage, selected object,
+  viewport, state, or workflow step.
+
+This is a technical consistency contract. Do not use it to claim visual parity.