@tiic-tech/openworkflow 0.1.0 → 0.1.2

package/skills/select-change/references/selection-protocol.md

@@ -0,0 +1,281 @@
+# Selection Protocol
+
+Use this reference when selecting one candidate from `CANDIDATE_CHANGES.yaml`
+and preparing implementation artifacts.
+
+## Selection Inputs
+
+Required:
+
+- `CANDIDATE_CHANGES.yaml`
+
+Optional:
+
+- `CANDIDATE_CHANGES.md` as a readable view
+- `CHANGE_ANALYSIS.yaml` as read-only cross-queue recommendation evidence
+- upstream source artifacts named by the queue
+- user constraints such as "choose C004" or "avoid runtime changes"
+- top-level queue `operations` for audit history
+- current branch and dirty-tree state from `git status --short --branch`
+
+If the user names a candidate id, verify that its dependencies are satisfied
+before selecting it. If the id is blocked, not ready, or `risk: high`, report
+why and stop unless the user explicitly approves the relevant risk or decision
+option.
+
+If the user provides multiple queues, first decide whether the request is a
+read-only comparison or an actual selection. Read-only comparison belongs to
+`analyze-changes`. Selection may consume a prior `CHANGE_ANALYSIS.yaml`, but it
+must still write artifacts inside one target queue.
+
+If there is only one active queue, do not require `analyze-changes`.
+`select-change` owns ranking within that queue: it should inspect candidate
+status, dependencies, risk, unlock value, selection policy, owned paths, and
+validation realism before selecting one candidate.
+
+## Feat And Commit Cadence
+
+The source `CANDIDATE_CHANGES.yaml` is the feature-level queue. Selection does
+not normally create a new top-level `changes/<id>/` folder. Instead, place
+candidate-specific planning artifacts inside the existing feat folder:
+
+```text
+changes/<plan_id>/
+  CANDIDATE_CHANGES.yaml
+  <candidate-id>-<slug>/
+    SELECTED_CHANGE.yaml
+    ATOM_TASKS.yaml
+    IMPLEMENTATION_BRIEF.md
+```
+
+Each selected candidate should be small enough to complete as one coherent git
+commit. When the candidate completes, update the queue with completion evidence
+and include the commit id when available.
+
+## Branch And Dirty-Tree Guards
+
+Before selecting, compare current git state with the queue boundary:
+
+- current branch from `git status --short --branch`
+- dirty paths from `git status --short --branch`
+- `queue_policy.branch_boundary` when present
+
+If the current branch differs from `queue_policy.branch_boundary`, stop before
+selection unless the user explicitly approves a planning-only exception or
+asks to continue on the current branch. Report the recorded branch, current
+branch, and exact resume condition. Do not run checkout or branch commands.
+
+If the tree is dirty, decide whether the paths are part of the current
+selection operation. A clean selection can create selection artifacts and update
+the queue. A dirty tree containing previous selected-change implementation,
+unrelated source edits, or generated surfaces should stop selection until that
+work is committed, stashed, or otherwise resolved by the user. Do not perform
+those git operations from this skill.
+
+Selection artifacts should state the expected commit boundary: the selected
+candidate should complete as one coherent commit unless it is split or
+superseded before implementation continues.
+
+## Cross-Queue Arbitration
+
+The normal path is one active `CANDIDATE_CHANGES.yaml` queue. Cross-queue
+arbitration is an explicit exception for moments when multiple active queues
+compete for the next selected change.
+
+Trigger cross-queue arbitration when:
+
+- the user supplies multiple queue paths
+- the user asks which active queue should go next
+- a `CHANGE_ANALYSIS.yaml` recommends a target plan and candidate
+- a legacy queue is being reactivated and must be compared against current work
+
+Do not silently scan all `changes/*/CANDIDATE_CHANGES.yaml` files during a
+single-queue selection. Broad discovery belongs to `analyze-changes` unless the
+user explicitly asks select-change to consume that global context.
+
+When consuming `CHANGE_ANALYSIS.yaml`:
+
+1. Treat it as advisory evidence, not as permission to select.
+2. Verify `recommendation.target_plan_id` and
+   `recommendation.target_candidate_id` against the target queue.
+3. Re-check status, dependencies, branch boundary, dirty tree, and high-risk
+   gates from current files.
+4. If the recommendation is stale, stop and name the queue maintenance or fresh
+   analysis needed.
+5. If the recommendation is still valid, create the selected-change folder
+   inside `changes/<target_plan_id>/`.
+
+Record cross-queue rejected alternatives in `SELECTED_CHANGE.yaml` with this
+shape:
+
+```yaml
+rejected_alternatives:
+  - plan_id: M68-post-proto-workflow-planning
+    candidate_id: H003
+    reason: High risk and missing a local high-risk decision report.
+```
+
+Use `id` only for alternatives from the same source queue when the surrounding
+artifact already names the source plan. Use `plan_id` plus `candidate_id` for
+cross-queue alternatives.
+
+Create a meta-selection or analysis artifact only when the user's requested
+output is the decision record itself. Do not use meta-selection artifacts as a
+shortcut around selecting one implementable candidate in its owning queue.
+
+## Targeted Candidate Review
+
+For point-to-point review, inspect only the requested candidate plus the
+dependencies, unlocks, operation history, and directly owned paths needed to
+judge readiness.
+
+Return:
+
+- `candidate_id`
+- `status`
+- `readiness`: ready, not_ready, blocked, already_done, or superseded
+- `dependency_status`
+- `scope_risks`
+- `validation_gaps`
+- `high_risk_report`: required, missing, present, or not_applicable
+- `recommended_operation`: query, select, update, split, defer, block,
+  supersede, or none
+
+This mode is read-first. It should not mutate the queue unless the user asks for
+the recommended operation to be applied.
+
+## Decision Order
+
+1. Stop on branch mismatch unless an explicit planning-only exception exists.
+2. Stop on unrelated dirty-tree work that would blur the commit boundary.
+3. Exclude `done`, `blocked`, `deferred`, and `superseded` candidates.
+4. Prefer `ready` candidates over plain `candidate` entries.
+5. When cross-queue arbitration is active, honor a current
+   `CHANGE_ANALYSIS.yaml` recommendation only after verifying it against the
+   target queue.
+6. In the normal single-queue path, honor `next_recommended_candidate_id` when
+   it is ready and coherent.
+7. Prefer candidates that unlock other candidates.
+8. Prefer focused owned paths over cross-module changes.
+9. Prefer clear validation over unclear or manual-only acceptance.
+10. Prefer lower-risk dogfood or source behavior before runtime exposure.
+11. Prefer the user's latest explicit sequencing when it does not violate risk
+   or dependency gates.
+12. Stop on `risk: high` unless explicit user approval names a concrete decision
+   option.
+
+When two candidates are close, pick the one that produces better evidence for
+the next planning decision.
+
+## High-Risk Selection Gate
+
+High-risk candidates require a decision report before selection. The report is
+usually `changes/<plan_id>/HIGH_RISK_DECISION_REPORT.md` and is defined in
+`references/planning-artifact-contracts.md`.
+
+When the best next candidate is `risk: high`:
+
+1. Check whether the queue links an existing high-risk decision report.
+2. If a report exists, summarize its concrete risks, options, recommended path,
+   guardrails, go criteria, and stop criteria.
+3. If no report exists, stop and recommend a `decompose-to-changes` maintenance
+   operation to create one.
+4. Do not create selection artifacts unless the user explicitly approves a
+   concrete option such as design-only, research-only, narrow spike, or full
+   implementation.
+
+Explicit approval must be more specific than "continue". It should identify the
+approved option or replacement candidate. If approval is ambiguous, ask for the
+decision option and do not select.
+
+When a high-risk candidate is approved and selected:
+
+- Include the approved option in `selection_reason`.
+- Add the report path to rejected alternatives or evidence.
+- Copy report guardrails into `IMPLEMENTATION_BRIEF.md` stop conditions.
+- Keep atom tasks scoped to the approved option, not the full high-risk surface.
+
+## SELECTED_CHANGE.yaml
+
+Include:
+
+- source plan id and source candidate id
+- concise selection reasons
+- rejected alternatives when the choice is not obvious; use `plan_id` and
+  `candidate_id` for cross-queue alternatives
+- includes and excludes copied from the selected candidate
+- owned paths copied from the selected candidate
+- forbidden paths inferred from the candidate exclusions and repo rules
+- acceptance and validation copied from the selected candidate
+
+Do not copy the entire candidate queue into this artifact.
+
+## ATOM_TASKS.yaml
+
+Break the selected change into tasks in this order:
+
+1. `read`: inspect existing context only when needed
+2. `edit` or `document`: make the core source/artifact change
+3. `verify`: run validation
+4. `document`: update queue status or handoff evidence when applicable
+
+Each task should have:
+
+- stable `task_id`
+- clear `title`
+- initial `status`
+- `type`
+- focused `owned_paths`
+- concrete `done_when`
+
+## IMPLEMENTATION_BRIEF.md
+
+Keep the brief short and operational. Include:
+
+- `Goal`
+- `Read First`
+- `Do`
+- `Do Not`
+- `Owned Paths`
+- `Validation`
+- `Stop Conditions`
+
+The brief is for the next implementation agent. It should not explain the
+entire planning conversation.
+
+## Queue Update
+
+After selecting:
+
+- set candidate `status` to `selected`
+- add `selection.selected_change_id`
+- add `selection.reason`
+- add `selection.selected_at` when the date is known
+- append a top-level `operations` entry with `operation_type: select`
+- update `next_recommended_candidate_id` only if the queue has another obvious
+  ready candidate
+
+After implementation completes, the implementation agent should set status to
+`done` and add completion evidence.
+
+## Operation Log Expectations
+
+When select-change mutates a queue, append an operation item:
+
+```yaml
+operations:
+  - operation_id: OP004
+    operation_type: select
+    target_candidate_ids:
+      - P002
+    actor: agent
+    reason: Candidate is ready and unlocks P005.
+    changed_at: 2026-05-21
+    before_status: ready
+    after_status: selected
+    evidence:
+      - changes/<selected-change-id>/SELECTED_CHANGE.yaml
+```
+
+Do not create selection artifacts without updating the operation log when the
+queue already uses `operations`.

package/skills/tune-prototype/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: tune-prototype
+description: Refine accepted prototype screens or prompt packs into screen-bound refined prototype prompt packs. Use when the user wants /ow:tune to preserve a baseline prototype product system while applying feedback, form-factor changes, screen-specific edits, or regeneration instructions before production planning.
+---
+
+# Tune Prototype
+
+## Purpose
+
+Convert accepted baseline prototype evidence and tuning feedback into a refined
+prompt pack without product drift. This skill is the source behavior for
+`/ow:tune`; it does not create first-pass strategic prototype directions and it
+does not implement production code.
+
+Tune work answers: how should an already accepted prototype screen group change
+while preserving the product system that made it worth accepting?
+
+## Inputs
+
+Required:
+
+- baseline prototype screens, screenshots, screen descriptions, generated image
+  outputs, or an accepted `PROTO_PROMPT_PACK.yaml`
+- direct user tune/refinement request
+
+Optional:
+
+- baseline prompt pack or prior `REFINED_PROTO_PROMPT_PACK.yaml`
+- product vision or selected strategic direction
+- screen map, accepted direction, locked screens, target form factor, target
+  screen count, target tool, regeneration scope, output language, or constraints
+- `references/proto-redesign-artifact-contracts.md`
+- `skills/tune-prototype/references/refined-prompt-pack-protocol.md`
+
+Do not load unrelated specs, changes, runtime state, generated adapters, or
+production implementation history unless the tuning question explicitly depends
+on them.
+
+## Output
+
+Write artifacts under the active prototype or change path chosen by the
+workflow. The core artifact is a refined proto prompt pack matching
+`schemas/proto-prompt-pack.schema.json`.
+
+Expected files:
+
+```txt
+REFINED_PROTO_PROMPT_PACK.yaml
+REFINED_PROTO_PROMPT_PACK.md
+REVIEW_PLAN.md
+EVIDENCE.md
+```
+
+## Workflow
+
+1. Normalize baseline inputs: screen captures, screen descriptions, accepted
+   prompt pack, previous generated prompts, target tool, target form factor,
+   locked screens, and regeneration scope.
+2. Audit the full baseline screen group before writing prompts. Do not tune
+   from one representative screen unless the user explicitly limits scope.
+3. Extract the product system: thesis, primary loop, interaction model, feature
+   system, design language, copy rules, trust boundaries, anti-goals, stable
+   constants, and adaptable variables.
+4. Interpret the tune request as explicit additions, removals, transformations,
+   locked elements, and flexible areas. Surface conflicts or assumptions
+   briefly.
+5. Create `MUST_INHERIT`, `MUST_ADD`, `MUST_REMOVE`, and `FLEXIBLE_CHANGE`
+   rules, then apply them globally and per target screen.
+6. Build a screen mapping and prompt manifest with stable target screen IDs,
+   source screen IDs, generation order, dependencies, negative constraints, and
+   acceptance criteria.
+7. Write a global design system prompt and standalone screen-specific prompts.
+8. Review the pack against product continuity, screen binding, deletion
+   coverage, trust/privacy preservation, and downstream generation readiness.
+9. Run `npm run validate` when the repository validator exists.
+
+## Refinement Rules
+
+- Treat a prototype screen group as a product system, not a collection of
+  unrelated images.
+- Preserve product thesis, primary loop, core feature logic, emotional promise,
+  component vocabulary, copy tone, AI/system behavior, trust boundaries, and
+  user controls unless the user explicitly changes them.
+- Bind every refined prompt to a target screen ID, source screen ID(s),
+  generation scope, target form factor, and acceptance criteria.
+- Put requested removals in `MUST_REMOVE`, global negative constraints,
+  per-screen negative constraints, and acceptance checks.
+- Platform transformation should preserve intent over geometry. For example,
+  desktop outputs need native navigation, information density, and layout
+  patterns rather than widened mobile screens.
+- Multi-round tuning must import prior accepted `MUST_INHERIT` rules and keep
+  screen IDs stable unless screens are split, merged, deleted, or explicitly
+  renamed.
+- Do not introduce unrelated features, a new product model, or a new brand
+  direction unless the tune request explicitly asks for that.
+
+## Forbidden Defaults
+
+- Do not create first-pass strategic prototype directions; use
+  `build-prototype` for `/ow:proto`.
+- Do not create `SPEC.yaml`, `CHANGE.yaml`, `.codex/runtime/`, or Agent Team
+  artifacts from this skill.
+- Do not add `/ow:proto2html` or any HTML conversion behavior.
+- Do not expose runtime command surfaces or generated adapter surfaces.
+- Do not silently drop accepted baseline controls, privacy affordances, memory
+  controls, or non-goals during visual refinement.
+- Do not output anonymous refined prompts that cannot be traced back to source
+  and target screens.
+
+## Handoff
+
+After user review, hand off to `/ow:decision`, another `/ow:tune` round,
+design/spec planning, or another candidate change.
+
+Expected outcomes:
+
+- `continue`: refined prompt pack is strong enough for production planning
+- `tune`: another refinement pass is needed
+- `regenerate_selected`: selected screens need another image generation pass
+- `pivot`: adjust the strategic prototype direction or vision
+- `stop`: archive or clean the prototype path

package/skills/tune-prototype/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Tune Prototype"
+  short_description: "Refine screen-bound prototype prompt packs"
+  default_prompt: "Use /ow:tune to turn baseline prototype screens and tuning feedback into refined screen-bound prompt packs."

package/skills/tune-prototype/references/refined-prompt-pack-protocol.md

@@ -0,0 +1,161 @@
+# Refined Prompt Pack Protocol
+
+Use this reference when `/ow:tune` should convert accepted baseline screens and
+user feedback into a screen-bound refined prompt pack.
+
+## Input Normalization
+
+Collect or infer:
+
+- baseline screen sources: screenshots, screen descriptions, source screen IDs,
+  accepted generated outputs, or prior prompt pack
+- baseline prompt text when available
+- tune request
+- product vision or strategic direction when available
+- target form factor, target tool, target screen count, locked screens,
+  regeneration scope, language, and constraints
+
+Require at least one baseline input and one tune request. If the user provides a
+screen group, audit the group before writing prompts.
+
+## Baseline Screen Audit
+
+For each source screen, record:
+
+- source screen ID and inferred screen name
+- journey stage, user goal, and system state
+- represented feature and primary action
+- core components and screen-specific copy tone
+- AI/system behavior
+- trust, privacy, safety, memory, and user-control affordances
+- visual cues and product-specific motifs
+- elements that must be preserved
+- platform artifacts to transform or remove
+- assumptions or missing evidence
+
+## Product System Extraction
+
+Extract the continuity rules that should survive the next generation pass:
+
+- product thesis and target user
+- primary behavior loop
+- brand promise and emotional job
+- interaction model and information architecture
+- feature system and component vocabulary
+- visual language and copywriting system
+- trust, boundary, privacy, and safety system
+- anti-goals
+- stable constants and adaptable variables
+
+## Tune Interpretation
+
+Translate the user's request into explicit deltas:
+
+- additions: new screens, components, states, copy, actions, system behavior,
+  platform patterns, or trust controls
+- removals: unwanted features, visual artifacts, incorrect brand elements,
+  forbidden UI patterns, obsolete copy, or unsafe AI representations
+- transformations: form-factor adaptation, journey reshaping, layout changes,
+  component transformations, or state changes
+- locked elements: screens or product-system traits that must not move
+- flexible areas: safe exploration space that remains inside the product
+  thesis, brand promise, non-goals, and screen purpose
+
+If additions and removals conflict with baseline continuity, state the
+assumption before producing prompts.
+
+## Delta Rules
+
+Write global and screen-level rules in four buckets:
+
+- `MUST_INHERIT`: product thesis, primary loop, core features, emotional
+  promise, visual motifs, component vocabulary, copy tone, system behavior,
+  trust boundaries, screen purpose, and locked content
+- `MUST_ADD`: requested screens, components, states, copy, actions, system
+  behavior, target-platform patterns, and controls
+- `MUST_REMOVE`: requested removals, platform artifacts, obsolete copy,
+  incorrect AI representations, and forbidden UI patterns
+- `FLEXIBLE_CHANGE`: layout composition, card arrangement, copy phrasing within
+  tone rules, icon details, hierarchy, spacing, and target-native density
+
+Requested removals must appear in global negative constraints, per-screen
+negative constraints, and acceptance checks.
+
+## Prompt Pack Structure
+
+`REFINED_PROTO_PROMPT_PACK.yaml` should follow
+`schemas/proto-prompt-pack.schema.json` and include:
+
+- `prompt_pack_type: refined_proto_prompt_pack`
+- `source`
+- `baseline_audit`
+- `product_system`
+- `delta_rules`
+- `screen_manifest`
+- `global_design_prompt`
+- `screen_prompts`
+- `negative_constraints`
+- `review_plan`
+
+`REFINED_PROTO_PROMPT_PACK.md` should be the human-readable view.
+
+Each screen prompt needs:
+
+- `prompt_id`
+- `target_screen_id`
+- `screen_name`
+- source screen IDs
+- target form factor and canvas
+- strategic purpose and user goal
+- system state
+- must inherit, add, remove, and flexible change rules
+- layout structure and required components
+- required copy or copy rules
+- interaction states and AI/system behavior
+- trust, privacy, safety, and user-control requirements
+- visual style rules
+- negative constraints
+- desired user feeling
+- acceptance criteria
+
+## Screen Manifest
+
+Use stable IDs:
+
+- source screens: `SRC_M01`, `SRC_W01`, `SRC_T01`, or `SRC_01`
+- target screens: `WEB_S01`, `MOB_S01`, `TAB_S01`, or `REFINE_S01`
+- prompt IDs: `PROMPT_WEB_S01`, `PROMPT_MOB_S01`, or similar
+
+For each target screen, include:
+
+- target screen ID and name
+- prompt ID
+- source screen IDs
+- target form factor and canvas
+- journey stage
+- generation scope: `CREATE_NEW`, `TRANSFORM`, `REFINE`, `REGENERATE`,
+  `LOCKED`, `MERGE`, `SPLIT`, or `DELETE`
+- generation order and dependencies
+- locked elements
+- per-screen delta rules
+- prompt and negative prompt
+- acceptance criteria
+
+Preserve screen IDs across rounds unless the screen is deleted, split, merged,
+or explicitly renamed.
+
+## Quality Gate
+
+Revise before finishing if:
+
+- only one source screen was considered from a supplied group
+- visual style changed but product loop, feature system, or trust controls were
+  lost
+- requested removals are absent from negative constraints or examples
+- prompts are not bound to target screens and source screens
+- desktop outputs read like widened mobile layouts
+- new screens feel like unrelated product ideas
+- the downstream generator would need extra context to produce the screens
+
+The final pack should let a reviewer trace every generated screen back to the
+baseline product system and the user's requested deltas.