@tiic-tech/openworkflow 0.1.1 → 0.1.2

package/skills/build-vision/references/proto-readiness-rubric.md

@@ -0,0 +1,48 @@
+# Proto-Readiness Rubric
+
+Use this rubric before compiling final vision artifacts.
+
+## Ready
+
+The vision is proto-ready when `/ow:proto` can generate high-quality prototype
+prompt packs without inventing the core strategy.
+
+Required signals:
+
+- target user is concrete
+- usage context is clear
+- current alternative is named
+- pain is specific
+- desired behavior change is explicit
+- core mechanism is understandable
+- core differentiator is not generic
+- strongest success signal is observable
+- failure signals are named
+- trust and privacy boundaries are explicit
+- non-goals can become prompt constraints
+- validation target is clear
+
+## Thin
+
+The vision is thin when fields exist but do not constrain downstream prototype
+generation. For example:
+
+- target user is "everyone"
+- success signal is "users like it"
+- differentiator is "AI-powered"
+- non-goals are missing
+- trust boundaries are implied but not explicit
+
+Thin vision should continue interview mode.
+
+## Blocked
+
+The vision is blocked when:
+
+- target user and product mechanism conflict
+- user intent contradicts privacy or safety constraints
+- the product direction depends on a decision the user has not made
+- downstream prototype prompts would require inventing product strategy
+
+Blocked vision should record the blocker or ask for the missing decision.
+

package/skills/build-vision/references/vision-interview-protocol.md

@@ -0,0 +1,48 @@
+# Vision Interview Protocol
+
+Use this reference when `/ow:vision` is in interview mode.
+
+## Goal
+
+Keep the human conversation fluid while digging deeply enough to produce a
+vision that downstream prototype generation can trust.
+
+## Interview Stance
+
+Act as:
+
+- product partner: look for leverage, sequencing, differentiation, and product
+  shape
+- requirements interrogator: expose thin answers, contradictions, and hidden
+  assumptions
+- intent compiler: translate answers into stable product intent
+
+## Question Rules
+
+- Ask one focused question at a time.
+- Prefer a concrete next question over a broad checklist.
+- Follow the user's answer rather than a fixed order.
+- Offer choices only when they help the user think.
+- Continue asking when a load-bearing dimension is thin.
+- Do not compile because a fixed number of questions has been reached.
+
+## Deepening Patterns
+
+Use these patterns when an answer is shallow:
+
+- "What would the user do today without this?"
+- "What behavior should change after this exists?"
+- "What would prove this is working?"
+- "What should this product refuse to become?"
+- "Where would trust break?"
+- "What would make the first prototype obviously wrong?"
+- "Which part is the real bet?"
+
+## Stop Conditions
+
+Stop interviewing only when:
+
+- proto-readiness is strong enough for `/ow:proto`
+- unresolved blockers are explicit
+- the user confirms compile can begin
+

package/skills/coder/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: coder
+description: Internal Agent-only code execution governance for OpenWorkflow source edits. Use as the source skill for future internal /ow:coder protocol work, not as a user-facing coding command.
+---
+
+# Coder
+
+## Purpose
+
+`coder` is the repo-owned source skill for OpenWorkflow's internal code quality
+governance protocol. It turns source-edit work into a governed engineering
+loop: recover trust, map ownership, produce RED/GREEN evidence when applicable,
+self-check the diff, choose an honest validation ladder, and bind evidence back
+to the current selected change or run.
+
+This is not a generated runtime surface and not a public workflow command. The
+semantic command boundary is defined in `references/internal-coder-protocol.md`.
+
+## Boundary
+
+Internal only:
+
+- Agent-only engineering quality protocol
+- source-edit preflight
+- RED/GREEN evidence discipline
+- post-write self-check
+- validation ladder selection
+- evidence binding and quality lesson promotion
+
+Not owned here:
+
+- user-facing "write code" behavior
+- `/ow:change` selected-change planning
+- `/ow:team` runtime orchestration
+- command registry exposure
+- generated `.agents/**` output
+- mandatory `CODER_EVIDENCE.yaml`
+- public CLI JSON changes
+
+## Read First
+
+- `references/internal-coder-protocol.md`
+- `references/validation-trust-domains.md`
+- `references/skill-system-lifecycle.md`
+- `references/git-version-control-governance.md`
+
+Use the system-level `ow-code-quality-governor` material only as migration
+source and benchmark context. Durable OW behavior should live in this repo.
+
+## Trust Recovery
+
+Before source edits, establish the current trust surface with the repo-local
+CLI:
+
+```bash
+node dist/cli/src/index.js resume --root . --json
+node dist/cli/src/index.js handoff --root . --json
+node dist/cli/src/index.js inspect --root . --strict --json
+git status --short --branch
+```
+
+Use `resume` first after interruption, context loss, network failure, or
+unexpected termination. Use `handoff` and `inspect --strict` as trust gates, not
+as release-readiness proof.
+
+## Owner Map
+
+Before non-trivial edits, identify the source owner and the derived surfaces.
+
+Owner map:
+
+- command behavior: `packages/core/src/commands/registry.ts` or the matching
+  CLI command module
+- artifact shape: artifact registry, schema, validator, and summary policy
+- generated Codex surfaces: source registry or adapter template followed by
+  `sync`
+- summary and handoff trust: `packages/core/src/workflow/summaryHealth.ts`
+- planning queue state: `changes/<plan_id>/CANDIDATE_CHANGES.yaml`
+- git evidence: selected-change `LOCAL_COMMIT_EVIDENCE.yaml`
+- docs or source skills: repo-owned `references/` and `skills/`
+
+If the same rule appears in two owners, either collapse the duplication or
+record the temporary compatibility boundary in the selected change.
+
+## File Map
+
+For changes touching more than one concern, name the intended file set before
+editing:
+
+- core model or helper files for source truth
+- CLI files for command/report wiring only
+- adapter files for generated formatting only
+- dev verifier or fixture files for structural checks
+- planning artifacts for queue status and evidence
+
+Do not patch generated `.agents/**` as the durable fix. Change the source owner
+and regenerate through the repo-local CLI when generated surfaces are in scope.
+
+## RED Evidence
+
+For behavior, validator, CLI report, generated-surface, path-safety, summary,
+queue, or git-evidence changes, prefer RED evidence before production edits.
+
+Valid RED evidence:
+
+- failing parsed JSON or YAML assertion
+- failing valid or invalid fixture
+- failing generated-surface parity check
+- failing summary, handoff, or resume health assertion
+- targeted compile or runtime verifier failure
+
+RED can be marked not applicable for docs-only contract work, mechanical
+renames, or exploratory spikes. In those cases, use the nearest structural
+check and record why RED is not useful.
+
+## GREEN Evidence
+
+After edits, rerun the RED evidence or nearest equivalent. Then run the rest of
+the validation ladder that matches the touched trust domain.
+
+Do not treat `npm run build` alone as validation. Do not hide existing broad
+repo failures; classify them as active-change failures, historical archive
+debt, fixture debt, or release-readiness debt.
+
+## Post-Write Self-Check
+
+Before final validation, inspect the diff for:
+
+- accidental second source of truth
+- hidden dependency or broad scan
+- generated-surface edits without source changes
+- oversized files gaining a new unrelated concern
+- comments that explain what instead of why
+- validation that does not match the touched trust domain
+- queue completion without selected-change commit evidence when implementation
+  files changed
+
+Fix any issue immediately or record it as explicit residual quality debt tied
+to a follow-up candidate.
+
+## Validation Ladder
+
+Use the narrowest honest ladder:
+
+- docs or planning contract: YAML parse when relevant, `handoff`, `inspect
+  --strict`, `resume`, and `git diff --check`
+- source skill or generated protocol: `npm run build`, `sync --root . --tools
+  codex --json`, generated diff review, `inspect --strict`, and `git diff
+  --check`
+- command registry or generated runtime surface: build, sync, runtime-surface
+  verifier, and generated diff review
+- artifact/schema/validator: build, validate, and targeted valid/invalid
+  fixtures
+- recovery or summary trust: handoff, inspect, summaries, resume, and targeted
+  fixture or command packet
+- git evidence: git-automation preview/write plus strict read-model commands
+
+## Evidence Binding
+
+Bind implementation evidence to the current OW selected change:
+
+- `SELECTED_CHANGE.yaml` owns scope, acceptance, owned paths, forbidden paths,
+  and expected validation.
+- `ATOM_TASKS.yaml` owns task status and verification results.
+- `IMPLEMENTATION_BRIEF.md` owns the handoff for the next implementation Agent.
+- `LOCAL_COMMIT_EVIDENCE.yaml` records local commit hashes and validation
+  evidence when implementation files changed.
+- Optional `LOCAL_COMMIT_EVIDENCE.yaml.coder_evidence` records coder preflight,
+  RED/GREEN, self-check, validation ladder, and lessons when those details are
+  useful. Missing `coder_evidence` is valid; malformed present evidence is not.
+
+Do not batch multiple completed selected changes into one checkpoint commit.
+Remote push, PR creation, Issue mutation, and merge require separate explicit
+approval.
+
+## Continuous Growth Loop
+
+Promote a quality lesson into source policy only when it is repeated,
+high-leverage, and backed by implementation or validation evidence.
+
+Use `references/coder-continuous-growth-loop.md` as the source policy for
+promotion criteria, evidence requirements, and boundaries. Session notes,
+unreviewed memories, or one-off fixes are not enough to change durable coder
+policy by themselves.
+
+Promotion targets:
+
+- role or stance: this skill
+- source-of-truth or architecture rule: `references/`
+- validation ladder or evidence rule: this skill plus the relevant reference
+- generated-surface behavior: command registry or adapter source, then sync
+
+Do not write project-local SOUL or MEMORY artifacts from this skill. Future
+project memory promotion needs its own governed persistence and pruning rules.
+
+## Handoff
+
+When coder governance is satisfied, report:
+
+- source truth changed
+- generated surfaces refreshed or intentionally untouched
+- validation commands run
+- commit evidence path when implementation files changed
+- residual quality debt and next candidate, if any

package/skills/decompose-to-changes/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: decompose-to-changes
+description: Create, update, query, or maintain an OpenWorkflow CANDIDATE_CHANGES queue from explicit source text, the latest planning discussion, or selected repo artifacts. Use when a broad goal, roadmap topic, prototype redesign, feature idea, or existing candidate queue needs to be split into focused implementable changes, surgically edited by candidate id, or prepared before select-change or implementation begins.
+---
+
+# Decompose To Changes
+
+## Purpose
+
+Turn ambiguous planning input into a durable candidate change queue. This skill
+plans change boundaries; it does not select one change for implementation and
+does not implement code.
+
+## Feat Boundary
+
+Treat each `CANDIDATE_CHANGES.yaml` produced by this skill as one complete feat
+boundary. The top-level folder `changes/<plan_id>/` owns the feat-level queue,
+summary, and audit history. Candidate changes inside that queue are
+commit-sized slices of the feat, not separate top-level feats.
+
+Before writing candidates, perform a scope triage. A queue may cover one
+feature, one bounded module, one command surface, one artifact family, or one
+workflow slice. It must not become a roadmap bucket for multiple features or a
+large module family just because the source discussion contains a deep vision.
+
+When the source includes more features than the current queue can responsibly
+own, record those features as future refs in `scope_control.deferred_features`
+or `SUMMARY.yaml` notes. Do not include them as current `changes` candidates
+unless they are inside the selected queue boundary.
+
+Create a new top-level `changes/<plan_id>/` only for a new decomposition queue,
+product theme, or broad planning source. When the current queue still owns the
+work, maintain that queue and let `select-change` create candidate-specific
+selection artifacts inside the existing feat folder.
+
+## Branch Boundary
+
+When creating a new feat queue, capture the current branch from
+`git status --short --branch` and decide the intended feat branch. Record it in
+`queue_policy.branch_boundary` and in `SUMMARY.yaml`.
+The branch boundary should carry the same feat identity as the queue `plan_id`
+when practical; for example, `M114-engineering-quality-foundation` should
+normally use a branch containing `m114`.
+
+Do not automatically create or switch branches from this skill. If the agent or
+user already created the branch, record it. If the queue is being planned before
+branch creation, record the proposed branch name and note that the branch still
+needs to be created before implementation begins.
+
+For queue maintenance, preserve the existing branch boundary. If the current
+branch differs, record the observation in the operation reason or summary notes
+instead of silently changing the boundary.
+If the branch boundary names another plan id, do not silently treat it as the
+owning feat branch. Record a narrow `queue_policy.branch_identity_exception`
+only when the user has explicitly approved temporary continuation on that
+branch, with `mode: temporary_continuation_branch`, `approved: true`,
+operation-scoped `allowed_operations`, and a reason.
+
+## Read First
+
+Read these only as needed:
+
+- `references/planning-artifact-contracts.md`
+- `skills/decompose-to-changes/references/decomposition-protocol.md`
+- Existing `CANDIDATE_CHANGES.yaml` when updating a queue
+- User-specified source files or the latest session discussion
+
+## Workflow
+
+1. Run `git status --short --branch` and note whether the tree is dirty.
+2. Decide whether this is decomposition mode or queue maintenance mode:
+   - use decomposition mode for new broad goals or new planning sources
+   - use queue maintenance mode for add, query, update, defer, block,
+     supersede, split, merge, or priority changes in an existing queue
+3. Identify the planning source:
+   - explicit user-provided text or files first
+   - latest session discussion when the user refers to "current discussion"
+   - repo vision, roadmap, or existing OpenWorkflow artifacts only when needed
+4. Choose a `plan_id` and output location. Default to
+   `changes/<plan_id>/CANDIDATE_CHANGES.yaml`; this folder is the feat root for
+   all candidate commits in the queue.
+5. In decomposition mode, choose or confirm the feat branch boundary and record
+   it as `queue_policy.branch_boundary`.
+6. If updating an existing queue, preserve existing candidate ids, branch
+   boundary, and history.
+   Add new ids only for genuinely new candidates.
+7. Run the queue scope gate:
+   - name the current feature boundary in `scope_control.current_boundary`
+   - decide which discussed features are outside that boundary
+   - record outside features as deferred refs, not current candidates
+   - if the remaining queue would still span multiple features or a broad
+     module family, split the planning source into separate future queues
+8. Decompose the in-bound source into candidates with focused owned paths, explicit
+   includes and excludes, dependencies, validation, and acceptance.
+9. For queue maintenance, write an `operations` entry for every targeted
+   change. Include the operation type, target id, reason, and evidence.
+10. If the current queue reaches one or more `risk: high` candidates that need
+   user confirmation, create or update `HIGH_RISK_DECISION_REPORT.md` in the
+   owning queue folder before implementation continues.
+11. Write `CANDIDATE_CHANGES.yaml` first. Then write
+   `CANDIDATE_CHANGES.md` as a non-authoritative readable view.
+12. Write `SUMMARY.yaml` with source refs, candidate count, branch boundary,
+    key dependencies, risks, and the optional next recommended candidate.
+13. Run repository validation when available, usually `npm run validate`.
+
+## Candidate Rules
+
+- Assign stable ids such as `C001`, `C002`, `C003`.
+- Prefer one module, feature, command surface, artifact family, or workflow
+  slice per candidate.
+- Prefer one feature, bounded module, command surface, artifact family, or
+  workflow slice per queue. A queue that needs several independent feature
+  outcomes is too broad even when every candidate is individually small.
+- Split candidates that require unrelated owned paths or mix planning,
+  implementation, and runtime exposure.
+- Do not include "later but known" features as normal candidates in the current
+  queue. Capture them as deferred refs with enough title, rationale, and
+  suggested future queue hints for a later DTC pass.
+- Use dependencies and unlocks instead of forcing one sorted backlog.
+- Set `next_recommended_candidate_id` only when one candidate clearly unlocks
+  the rest.
+- Keep Markdown synchronized with YAML, but treat YAML as the source of truth.
+
+## Queue Maintenance
+
+For an existing queue, operate by stable candidate id.
+
+- `query`: inspect one candidate or a filtered set without changing status.
+- `add`: append a new candidate with a new stable id.
+- `update`: revise scope, dependencies, validation, acceptance, or notes
+  without changing the candidate's identity.
+- `split`: keep the original candidate as `superseded` or narrowed, then add
+  replacement candidates with new ids.
+- `merge`: mark redundant candidates as `superseded` and point to the survivor.
+- `defer`, `block`, `restore`, `supersede`, `complete`: status transitions
+  with evidence.
+- `remove`: do not hard-delete a historical candidate. Use `superseded`,
+  `deferred`, or `blocked`. Hard deletion is allowed only for a malformed
+  candidate created in the same uncommitted operation, and the operation log
+  must say why.
+
+Every maintenance edit must append an `operations` item to the YAML queue and
+refresh the Markdown readable view.
+
+## High-Risk Reports
+
+When a queue's next actionable work is `risk: high`, or when the user asks for a
+high-risk stop/report, produce a `HIGH_RISK_DECISION_REPORT.md` instead of
+selecting or implementing the candidate. Use
+`references/planning-artifact-contracts.md` for the report contract.
+
+High-risk report behavior:
+
+- Keep candidate ids and candidate statuses stable unless the user explicitly
+  approves a status change.
+- Create the report under the owning queue folder, usually
+  `changes/<plan_id>/HIGH_RISK_DECISION_REPORT.md`.
+- Update an existing report when it covers the same decision boundary; do not
+  create duplicate reports for the same high-risk stop.
+- Link the report from `SUMMARY.yaml` outputs or notes.
+- Add an `operations` entry with `operation_type: query` or `block` and the
+  report path as evidence.
+- Treat the report as a decision packet, not as approval to implement.
+
+The report must include concrete risks, decision options, a recommended path,
+guardrails, go criteria, stop criteria, and validation expectations.
+
+## Boundaries
+
+- Do not create `SELECTED_CHANGE.yaml`, `ATOM_TASKS.yaml`, or
+  `IMPLEMENTATION_BRIEF.md`; that is `select-change`.
+- Do not implement a candidate.
+- Do not hand-edit generated `.agents/` or `.openworkflow/` surfaces unless the
+  selected source explicitly owns those paths and the user accepts that scope.
+- Do not delete completed, superseded, or deferred candidates. Update status
+  and append evidence instead.

package/skills/decompose-to-changes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Decompose to Changes"
+  short_description: "Turn planning input into focused candidate changes."
+  default_prompt: "Create a focused CANDIDATE_CHANGES queue from the latest planning discussion or the provided source text."